web-dev-qa-db-ja.com

すべてのドキュメントを自動生成するPythonパッケージの内容

Sphinxを使用してコードベースの基本的なドキュメントを自動生成しようとしています。ただし、Sphinxにファイルを再帰的にスキャンするように指示するのは困難です。

私はPython codebaseのようなフォルダ構造を持っています：

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

私は<workspace>でsphinx-quickstartを実行したので、構造は次のようになります。

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

クイックスタートチュートリアル http://sphinx.pocoo.org/tutorial.html を読みましたが、まだドキュメントを理解しようとしていますが、その言葉の仕方から、Sphinxはコードベースのすべてのモジュール/クラス/関数のドキュメントファイルを手動で作成します。

ただし、「automodule」ステートメントに気づき、クイックスタート時にautodocを有効にしたので、ほとんどのドキュメントが自動的に生成されることを期待しています。 conf.pyを変更してsrcフォルダーをsys.pathに追加し、次にautomoduleを使用するようにindex.rstを変更しました。だから今私のindex.rstは次のようになります：

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

私はサブパッケージで定義された数十のクラスと関数を持っています。しかし、私が実行すると：

sphinx-build -b html . ./_build

それは報告します：

updating environment: 1 added, 0 changed, 0 removed

そして、これは私のパッケージ内に何もインポートすることに失敗したようです。生成されたindex.htmlを表示しても、「Contents：」の横には何も表示されません。インデックスページには "mypackage（モジュール）"のみが表示されますが、クリックするとコンテンツも表示されません。

手動ですべてのクラスをリストする必要なしに、Sphinxにパッケージを再帰的に解析し、それが遭遇するすべてのクラス/メソッド/関数のドキュメントを自動的に生成するように指示するにはどうすればよいですか？

pythondocumentationdocumentation-generationpython-sphinx
51
Cerin

おそらくapigen.pyが役立ちます： https://github.com/nipy/nipy/tree/master/tools 。

このツールについては、ここで非常に簡単に説明しています： http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912 。

さらに良いことに、 pdoc を使用します。

更新： sphinx-apidoc ユーティリティがSphinx バージョン1.1 に追加されました。

17
mzjn

あなたはsphinx-apidocを使ってみることができます。

$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.

次のように、docプロジェクト全体を作成するために、sphinx-apidocとsphinx-quickstartを混在させることができます。

$ sphinx-apidoc -F -o docs project

この呼び出しは、Pythonモジュールの（プロジェクト）でsphinx-quickstartとLookを再帰的に使用して完全なプロジェクトを生成します。

お役に立てれば！

57
Daniel

注

Sphinx（実際には、Pythonインタープリター）がモジュールを見つけるには、それがインポート可能でなければなりません。つまり、モジュールまたはパッケージがsys.pathのいずれかのディレクトリーにある必要があります。 – sys.pathを調整します構成ファイルに応じて

だから、あなたのconf.pyに行き、追加してください

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

これで、index.rstは次のようになります。

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

そして

make html

5
macm