問題タブ [sphinx-napoleon]

Sphinxを使用して大規模なPythonコードベースのAPIドキュメントを自動的に作成しようとしています。

build_modules.pyとsphinx-apidocを使用してみました。どちらを使用しても、パッケージとトップレベルモジュールの出力ディレクトリに最初のドキュメントを正常に作成できます。

ただし、を使用してビルドする場合

このタイプの何千ものエラーが発生します。

コードベース内のすべての単一のクラスとメソッドに対して。いくつかの実験で、autosummary / autoclassディレクティブが、すべてのクラスとメソッドに最初のファイルがあることを期待するtoctreeを作成していることを発見したと思います。

警告以外は、ドキュメントはうまく機能しているようですが、私はそれらを取り除きたいので、何かを誤って構成した可能性があると思います。

私もほぼ同じ効果でnipype/toolsを試しました。

apigen.pyとbuild_modref_templates.pyを変更して、これらの「欠落している」ドキュメントごとに、必要に応じてautoclass / autofunction/automethodsを使用して最初のスタブを作成しました。ただし、ビルドには非常に長い時間（10分）がかかり、最後のビルドステップでのメモリエラーが原因で最終的にクラッシュします。

すべての警告を作成するモジュールのrstファイルの例を次に示します。

これらの警告を解決する方法についてアドバイスをありがとうございます！sphinxサイトパッケージファイルの変更を伴うソリューションには近づかないようにしたいと思います。

私はNumpyのドキュメンテーション標準を読んでいますが、オブジェクト属性について言及していないようです-クラス属性のみです。

では、たとえば、次のことをどのように文書化すればよいでしょうか?

編集: Napoleonに切り替えていることに注意してください。これは、属性をサポートしていますが、特にクラスまたはインスタンス属性はサポートしていません。

Google コード スタイルを使用して関数をドキュメント化しようとしています。この関数は、sphinx をナポレオン拡張と共に使用してドキュメントを作成します。この関数は、2 つの引数を返す点で異常です。ナポレオンがこれを処理するとは思わない。もしそうなら、誰かがそれをどのように処理するか教えてもらえますか?

複数の引数を返すのはコーディング スタイルとして適切ではないというメッセージが表示されるかもしれませんが、これを行うことはできますか? 生成された html は、これらの 2 行を 1 つの引数の説明の一部として扱います。サーバーとメッセージ行の間に改行を入れると役に立ちますが、それでも1つの引数を文書化しています。

この質問は、この他の質問に関連しています。提案され受け入れられた解決策は次のとおりです。

少なくとも私にとっては、この解決策は機能していません。arg1および説明を含むインデントされたサブブロックarg2は解析されません。

と Google スタイルの docstring をsphinx使用して複数の返品を管理するにはどうすればよいですか?sphinx.ext.napoleon

autodocと を使用して、Python 2.7 プロジェクトの Sphinx 駆動 (v1.3.1) ドキュメントをまとめていnapoleonます。1 つのディレクティブで文書化したい 1 つのモジュール内に、フラグautomodule::を適用する特定のクラスがあります。with に:special-members:フラグを立てると、モジュール内のすべてのスペシャルが表示されますが、これは良くありません。automodule:::special-members:

これどうやってするの？

autoclass::フラグが付けられたディレクティブを追加する:special-members:と、コンテンツの一部として「専門化されていない」ドキュメントが残りautomodule::、結果としてコンテンツが重複します。

:members:の命令で、スペシャルを対象としたクラスを除いて、モジュール内のすべてのクラスを明示的に入力できると思いますが、モジュールにautomodule::クラスを追加または削除するたびに、そのリストを更新することを忘れないでください。

Sphinx-Napoleon を使用して、Google スタイルの docstring でリスト、オプションの引数、ジェネレーターの戻り値の型を指定するにはどうすればよいですか?

私はもう試した

と

それぞれ; しかし、すべて生成されたドキュメントの残りの部分と一致しない不満足な出力を生成します。例えば

ただ与える

オプション[タイプ]

のリンクなしtype。

すべての組み込みテーマを試しましたが、同じ問題があります。

Sphinx-Napoleon で Google スタイルのドキュメント文字列を使用して、これらの要素をどのように文書化すればよいですか?

Python の関数は柔軟な型の引数を受け入れる場合があります。または、柔軟な型の値を返す場合があります。現在、そのような関数の良い例を思い出すことができないため、以下のおもちゃの例でそのような関数がどのように見えるかを示しています。

Sphinx のドキュメント表記法を使用して、そのような関数のドキュメント文字列を記述する方法を知りたいです。以下の例では、引数は または のいずれstrかintです。同様に、 または のいずれstrかを返しますint。

docstring の例を示しました (デフォルトの Sphinx 表記と、Sphinx のナポレオン拡張によって理解される Google 表記の両方)。これが柔軟な型を文書化する正しい方法であるかどうかはわかりません。

スフィンクスのデフォルト表記:

スフィンクス ナポレオン Google表記：

Sphinx によって処理されることを意図した docstring でパラメータまたは戻り値の複数の型を表現する正しい方法は何ですか?

私は Python API を作成しており、Google docstring規則を使用してソース内のすべてのクラスと関数を文書化しました。これは、Sphinx 規則よりもはるかに読みやすいことがわかりました。Sphinx を使用して API のドキュメントを作成したいと考えています。NumpydocとGoogle docstringsをサポートするNapoleonという拡張機能があるので、それを使用してみましたが、いくつか問題が発生しました。Ubuntu 12.04 で Python 2.7.3 を使用しています。

Sphinx 1.1.3 がインストールされています。ドキュメントの最初のステップを実行しました（sphinx-quickstart有効autodoc化されたmakeファイルを使用）。Sphinx 1.3 より前は、ドキュメントsphinxcontrib.napoleonの に拡張機能として追加する必要があったことを読みました。conf.py私はそれを行い、拡張機能napoleonが見つからないというエラーを受け取りました。ダウンロードしてインストールしたところ、特定のパッケージが見つからないというエラーが発生しました。

拡張 sphinxcontrib.napoleon をインポートできませんでした (例外: 名前 6 をインポートできません)

これは要件ファイル内のパッケージの名前だったので、インストールしました。別のパッケージでも同じエラーが発生したため、それもインストールしました。同じエラーが発生しましたが、「範囲」があります。

拡張 sphinxcontrib.napoleon をインポートできませんでした (例外: 名前範囲をインポートできません)。

どのパッケージかわかりません。どこにも見つからないので、行き詰まっています。念のため「sphinx.ext.napoleon」を試してみましたが、予想通り拡張子が見つかりませんでした。

そこで、Sphinx 1.3 と、Sphinx に同梱されている「sphinx.ext.napoleon」で試してみました。apt-get でインストールすると、更新後もバージョン 1.1.3 しか取得できません。そのため、Sphinx 1.3 を直接ダウンロードしてインストールしようとしましたが、次のエラーが発生しました。

setuptools に問題があるようです。この投稿を見つけて解決策を試しましたが、うまくいきません。

すべての docstring を変更できることはわかっていますが、それには時間がかかり、読みにくくなります。Sphinx 以外のものを試すこともできますが、Sphinx は Python の最も一般的なドキュメント ツールです。

ソース内のGoogle docstringから作成された適切なドキュメントを (まだ自動的に) 取得するにはどうすればよいですか?