問題タブ [autodoc]

私は sphinx autodoc拡張機能を使用しようとしています。具体的には、automodule作業中の django アプリのドキュメントを自動的に生成するディレクティブを使用しようとしています。問題は、プロジェクト内のすべてのクラス/関数を使用autoclassせずに、モジュール内のさまざまなクラスへの内部参照を作成したいことです。autofunction次のようなソース ファイルの場合:

次のようなスフィンクス ドキュメント ファイルを作成できるようにしたいと考えています。

XXXX-some-reference-to-A-XXXX にはどの参照を使用できますか? これを達成する簡単な方法はありますか？よろしくお願いします。

Sphinx ドキュメントに特定の関数の docstring だけを含めたいと思います。ただし、 http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.htmlを使用して、関連するクラスと関数の定義なしでこれらの詳細を表示するオプションはないようです。

Sphinx のドキュメントに *only* docstring を表示しますか? で説明されているように、クラスを作成しようとしました。しかし、これがテンプレートにどのように適合するかはわかりません。

また、autodoc-process-docstring イベント ハンドラを試してみましたが、うまくいきませんでした。

したがって、私のドキュメントが表示されるのではなく（現在のように）：

表示したいだけです：

.txt ファイルの現在のテンプレートは次のとおりです。

モジュールのドキュメント化に Sphinx の autodoc 拡張機能を使用しています。ドキュメント出力でモジュールのメンバーのフラットリストを取得したいと考えています。

私は以下を使用してみました：

ただし、これには 2 つの問題があります。

1. モジュールの docstring が含まれていますが、ここでは不要です。

2. 各エントリの名前には "modname." という接頭辞が付いていますが、これは完全に冗長です (このページはこのモジュールを説明するためのものであるため)。

ただし、すべてのモジュール メンバーの自動リストを取得しながら、これら 2 つの側面を選択的に無効にする構成オプションを見つけることができませんでした。

私の現在の計画は、 autofunction (など) を使用して、文書化するメンバーを明示的に列挙することですが、最初に望んでいたことを達成する簡単な方法を見逃していないかどうかを知りたいです。

更新:少なくとも 2 番目の部分の回避策を見つけました: set add_module_names=Falsein conf.py. ただし、これはグローバル設定であるため、元の質問には実際には答えません。

Sphinx autodocを使用して、関数docstringsからfabfileのドキュメントを生成することは可能ですか？

setup_developmentたとえば、私が試したタスクを含むfabfileの場合：

しかし、何も生成されません。

fabfileスニペット：

私はこの Cython クラスを持っています:

そして、Sphinx に次のように文書化してもらいたい:

class Sprite ( self, texture )
    何かをします。

だから私はそれを文書化しようとしました:

しかし、それも現れませんでした。私もこれを試しました：

今回は表示されましたが、スフィンクスは通常のようにこの情報を使って魔法のようなことをしませんでした:

class Sprite
    Sprite(self, texture)処理を行い

    ます。

では、どうすればよいのでしょうか。

Sphinx autodocを使用してクラスを文書化すると、属性の値は常に報告されますが（ここでは、＃437の下にあるはずです）、常に「=なし」として報告されます。

私はそれを次のように含めます

そして私のコードは次のようになります

「=なし」に実際の値を報告させる方法、またはそれを非表示にする方法はありますか？

Sphinx を使用して自分の小さなプロジェクトを文書化し始めようとしていますが、うまくいかないようです。

すでに検索しましたが、今まで試したことはすべてインポートエラーを修正しませんでした。

これがまさに私がやっていることです：

私もこれを試しました：

出力は有望に思えますが、実際に index.html を開くと、テスト モジュールのページのタイトルが完全に空白です。単にタイトルがあり、ドキュメント文字列などはありません。

ここで私が間違っていることを誰かが知っていますか? .. automodule + .. autoclass を配置すると、これらのドキュメントストリングが自動的に表示されると思いましたが、表示されません。

編集：

修正しましたが、理由がわかりません...今回は次のようにしました（以前とまったく同じだと思います）

ところで: コードの行数が多くて申し訳ありません。

編集2：

build/html ディレクトリをクリアすると、autodoc によってエラーは表示されませんが、モジュール用に生成されたファイルは空白になることがわかりました。docstring は表示されません (修正されたと言った前に、docstring が正しく表示されていたとしても...)。

空のフォルダー _sources および _static を build/html フォルダーに残すと、autodoc はモジュールを見つけられません。

本当に、何が起こっているのか理解できません。

編集3：

さて、これは非常にクレイジーです：

プログラムは決定論的ではないようですが、ランダムに「動作」します（モジュールのドキュメントファイルはまだ空です）。

今は、ソフトウェアを変更したほうがよいのではないかと考え始めています。

編集4：

モジュールの 1 つを書き直したところ、autodoc が完全に機能するようになりました... しかし、どのモジュールのインポートも変更していないので (おそらくモジュールのせいだと思いました)、これらの結果の変化に本当に困惑しています。

答えのない長い質問を書いて申し訳ありません。とにかく、何が起こっているのかを知っている誰かを楽しみにしています。

私は Sphinx を使い始めようとしていますが、容赦ない問題を抱えているようです。

指示：docs/sphinx-quickstart

私はすべての質問に答え、すべてがうまくいきます。

指示：docs/ls

すべてが正常に見えます。結果：build Makefile source

指示：sphinx-build -d build/doctrees source build/html

うまくいくようです。index.html ファイルを開くと、必要な「シェル」が表示されました。

実際のソース コードをsourceフォルダーとして配置しようとすると、問題が発生します。

指示：sphinx-build -d build/doctrees ../ys_utils build/html

結果：

私は Sphinx の完全な初心者であり、この種のドキュメントには比較的慣れていません。誰でもいくつかの提案を提供できますか?

編集：

これを処理するために Makefile を使用できるようにしたいと思います。現在、プロジェクトには 2 つのフォルダーがあります。

nextgen/ls

docs ys_utils

および今後使用する他のすべてのモジュールnextgen/docs/Makefileの HTML を生成する必要があります。ys_utils

CPython はドキュメントに autodoc を使用しません。手書きの散文を使用します。

PEP 3144 (ipaddress モジュール) については、sphinx-apidoc を使用して最初のリファレンス ドキュメントを生成したいと考えています。つまり、2 パス操作を実行したいということです。

1. sphinx-apidoc を使用して、autodoc に依存するモジュールの Sphinx プロジェクトを発行します

2. 新しい reStructuredText ソース ファイルを作成する sphinx ビルダーを実行します。すべての autodoc ディレクティブは、同じ出力を生成するインライン reStructuredText コンテンツとマークアップに置き換えられます。

最初のステップは簡単ですが、2 番目のステップを実行する方法がわかりません。また、これらの線に沿って既存のプロジェクトを検索する良い方法も思いつきません。

私はPythonライブラリを開発しており、sphinx.autodocを使用してドキュメントを生成しています。これは、自分自身を繰り返さず、ドキュメントとコードを一致させるための良い方法だと思います。

sphinx autodocからreStructuredTextを送信するためのコメントで？「CPythondocsビルドプロセスでautodocが有効になっていない（意図的な選択による）」ことを学びました。

なぜCPythonがそれを使用していないのか、使用することの欠点は何sphinx.autodocですか？