私はPythonライブラリを開発しており、sphinx.autodocを使用してドキュメントを生成しています。これは、自分自身を繰り返さず、ドキュメントとコードを一致させるための良い方法だと思います。
sphinx autodocからreStructuredTextを送信するためのコメントで？「CPythondocsビルドプロセスでautodocが有効になっていない（意図的な選択による）」ことを学びました。
なぜCPythonがそれを使用していないのか、使用することの欠点は何sphinx.autodocですか？
これは主に歴史の問題ですが、個人 (およびプロジェクト) の好みの問題でもあります。最近では、主に docstring に依存し、それらに散文を追加することで、非常に使いやすいドキュメントを取得できます。
ただし、CPython のドキュメントは、Sphinx の存在よりもずっと前から存在します (実際、Georg Brandl は、CPython の古いドキュメント システムを置き換えるために、Sphinx の初期バージョンを作成しました)。
そのため、ポリシーとして、docstring と散文ドキュメントは、autodoc の使用に依存せずに個別に維持されます。
また、標準ライブラリで reStucturedText docstring を使用することも許可していません。これにより、autodoc を使用する利点がさらに損なわれます。(PEP 287 Q & A の Q 10 を参照してください: http://www.python.org/dev/peps/pep-0287/#questions-answers )
最後に、Georg Brandlは、Sphinx の実行時に docstring を提供する標準ライブラリのバージョンが、ドキュメントを生成するものと正確に同じであることを確認するために注意する必要がある、CPython がいくぶん独特な立場にあることを指摘しました。うっかり間違ったバージョンを持ち込んでしまうだけでなく、動作中の Python ビルドとドキュメントの再生成の間に強い依存関係が生じてしまう可能性が非常に高くなります。
autodoc 側では、autodoc ベースのドキュメントを編集するときに、docstring の内容をインラインで簡単に見ることができないという問題があります。そのため、docstring のテキストと追加の散文を一緒によく読むことを確認するのが難しい場合があります。この問題は、 http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.htmlのようなブラウザの自動更新ソリューションによって軽減できます。
autodoc は、Python ソース ファイルに適切な依存関係を自動的に追加しないため、再構築の依存関係にも問題があります。docstring が変更されたにもかかわらず、Sphinx が関連する出力ファイルを再生成しなかったという問題が確かにありました。(これが修正されたとは思いませんが、より最近の Sphinx リリースで解決されている場合は、コメントでお知らせください。この観察を削除します)。
それらを別々に維持することで、より優れたドキュメントとより優れたドキュメント文字列が得られると思いますが（2つの文体はまったく同じではなく、生のドキュメント文字列は通常、reStructuredTextでマークアップされた場合よりもプレーンテキストとして読みやすいため）、それはアプローチですこれには、追加のメンテナンス作業にかかるかなりのコストと、不整合のリスクの増加が伴います。
したがって、ほとんどのサードパーティの Python プロジェクトでは、実際には標準ライブラリの例に従うことを避け、代わりに次のようにすることをお勧めします。
これは完全な解決策ではありませんが、このアプローチにより、docstring と散文ドキュメントの両方を最新の状態に保つための重複した作業を大幅に節約できます。