python - Sphinx を使用して Python パッケージを文書化する方法

Question

Python でパッケージを文書化しようとしています。現時点では、次のディレクトリ構造があります。

.
└── project
    ├── _build
    │   ├── doctrees
    │   └── html
    │       ├── _sources
    │       └── _static
    ├── conf.py
    ├── index.rst
    ├── __init__.py
    ├── make.bat
    ├── Makefile
    ├── mod1
    │   ├── foo.py
    │   └── __init__.py
    ├── mod2
    │   ├── bar.py
    │   └── __init__.py
    ├── _static
    └── _templates

このツリーは の起動の結果ですsphinx-quickstart。私はconf.pyコメントを外しsys.path.insert(0, os.path.abspath('.'))、私は持っていextensions = ['sphinx.ext.autodoc']ます。

私index.rstは：

.. FooBar documentation master file, created by
   sphinx-quickstart on Thu Aug 28 14:22:57 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to FooBar's documentation!
==================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

すべての__init__.py's には docstring があり、同じことがモジュールfoo.pyおよびbar.py. ただし、make htmlプロジェクトで実行すると、ドキュメントが表示されません。

Answer 1

概要は次のとおりです。

1. ソース内の docstring を使用してパッケージを文書化します。
2. sphinx-quickstartを使用して Sphinx プロジェクトを作成します。

3. sphinx-apidocを実行して、 autodocで使用するためにセットアップされた .rst ソースを生成します。詳細はこちら。

   このコマンドを-Fフラグとともに使用すると、完全な Sphinx プロジェクトも作成されます。API が大幅に変更された場合は、このコマンドを数回再実行する必要がある場合があります。

4. sphinx-buildを使用してドキュメントをビルドします。

ノート：

• Sphinx は、API ドキュメントを生成するために、automoduleまたはのようなディレクティブを含む .rst ファイルを必要とします。autoclassこれらのファイルがないと、Python ソースから何も自動的に抽出されません。これは、Epydoc や Doxygen などのツールの動作とは異なります。ここで違いがもう少し詳しく説明されています: docutils と Sphinx の関係は何ですか? .

• sphinx-apidoc を実行した後sys.path、autodoc がモジュールを検出できるように conf.py を調整する必要がある場合があります。

• これらの質問のような奇妙なエラーを回避するには、大規模なプロジェクトで OptionParser と sphinx-build の競合を解決するにはどうすればよいですか? 、OptionParser は sphinx と競合していますか? if __name__ == "__main__":、必要に応じてガードを使用して、コードが適切に構造化されていることを確認してください。