5

私はSphinxを使用していますが、本当に気に入っていますが、モジュールの概要がわかりません。エラーなどはありません。単純な...何もありません。これは私が自動文書化しようとしているモジュールです：

# vim: set fileencoding=utf-8 :
"""
.. module:: CONF
   :synopsis: Configuration module, tells where data files are.

.. moduleauthor:: Mr Anderson <mr@matrix.com>
"""

これは、ReSTインデックスファイルのSphinxディレクティブです。

.. automodule:: CONF
   :synopsis:

私はスフィンクスから他のあらゆる種類の素晴らしいものを手に入れているので、それは私にとって一般的に壊れていません。私が得る唯一の疑わしいことは：SEVERE: Duplicate ID: "module-CONF"。いくつかのグーグルは、このエラーは非常に「正常」であると私に信じさせましたか？

4

3 に答える 3

2

これが本当にあなたの質問に答えるかどうかはわかりませんが、おそらくあなたはあらすじが取り上げられるために「間違った」場所を探しています。automodule（あなたの指示があるところにそれが出てくることを期待することはかなり合理的であるように思われるので、「間違っている」 ）。モジュールマークアップに関するドキュメントから（私の強調）：

概要オプションは、モジュールの目的を説明する1つの文で構成する必要があります。現在、グローバルモジュールインデックスでのみ使用されています。

したがって、モジュールのコメント文字列の場合：

"""

.. module:: CONF
  :synopsis: Configuration module, tells where data files are.
    continuation possible here... (though goes against the point of synopses...)
  :platform: Windows

"""

概要はモジュールインデックスに表示されます-次のようなもの

c

CONF （Windows） 構成モジュール、 ...。

または、モジュールのコメント文字列（インデントに注意）の場合：

"""

:synopsis: Configuration module, tells where data files are to.

"""

automodule::ディレクティブに配置した場所にレンダリングされますが、モジュールインデックスにはレンダリングされません。私にとってのスタイリングは、パラメーターがメンバー関数でレンダリングされるときです。

やや厄介な回避策として、これら2つの宣言を組み合わせることができますが:synopsis:、明らかにそれはあまり維持可能ではありません。

于 2013-01-16T22:22:20.107 に答える
2

ディレクティブ:synopsis:でオプションを間違って使用していると思います。automoduleこのオプションは、 と同じように使用しautomoduleますmodule。:synopsis:つまり、いずれかのディレクティブのオプションで概要をインラインで指定する必要があります。

通常、両方ではなく、ディレクティブまたはディレクティブのいずれかを使用moduleしますautomodule。これが、重複に関する警告が表示される理由でもあります。残念なことに、私が見つけた限りでは、使用している場合、docstring に概要を含める方法はありません。automodule

したがって、警告を表示せずに automodule と synopsis を使用したい場合は、次のようにする必要があると思います。

.. automodule:: CONF
   :synopsis: Configuration module, tells where data files are.

次に`.. module::、src ファイル自体のディレクティブを削除します。

あなたのやり方でうまくいくと思いますが、その警告が表示されます。また、:synopsis:オプションをautomodule: から削除する必要があります。その後に実際の概要文字列が続くと、何の役にも立たず、「空の」概要が作成される可能性があります。

于 2013-01-17T16:05:03.770 に答える