55

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

次のようなフォルダ構造を持つPythonコードベースがあります。

<workspace>
└── src
    └── mypackage
        ├── __init__.py
        │   
        ├── subpackageA
        │   ├── __init__.py
        │   ├── submoduleA1
        │   └── submoduleA2
        │   
        └── subpackageB
            ├── __init__.py
            ├── submoduleB1
            └── submoduleB2

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

<workspace>
├── src
│   └── mypackage
│       ├── __init__.py
│       │
│       ├── subpackageA
│       │   ├── __init__.py
│       │   ├── submoduleA1
│       │   └── submoduleA2
│       │
│       └── subpackageB
│           ├── __init__.py
│           ├── submoduleB1
│           └── ubmoduleB2
│
├── index.rst
├── _build
├── _static
└── _templates  

クイックスタートチュートリアルを読みましたが、まだドキュメントを理解しようとしていますが、その言い回しでは、コードベース内のすべてのモジュール/クラス/関数のドキュメントファイルを手動で作成することをSphinxが想定しているのではないかと心配しています。 。

ただし、「automodule」ステートメントに気づき、クイックスタート中にautodocを有効にしたので、ほとんどのドキュメントが自動的に生成されることを期待しています。conf.pyを変更してsrcフォルダーをsys.pathに追加してから、index.rstを変更してautomoduleを使用しました。これで、私の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に指示するにはどうすればよいですか?

4

4 に答える 4

60

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>.

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

$ sphinx-apidoc -F -o docs project

この呼び出しは、sphinx-quickstartを使用して完全なプロジェクトを生成し、Pythonモジュールの<module_path>(プロジェクト)を再帰的に検索します。

于 2011-11-10T20:44:45.350 に答える
18

おそらく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で追加されました。

于 2011-01-06T17:32:49.080 に答える
5

ノート

Sphinx(実際にはSphinxを実行するPythonインタープリター)がモジュールを見つけるには、モジュールがインポート可能である必要があります。つまり、モジュールまたはパッケージはsys.pathのディレクトリの1つにある必要があります–それに応じて構成ファイルの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

于 2013-08-22T17:52:18.557 に答える
2

Sphinxバージョン3.1(2020年6月)以降、sphinx.ext.autosummaryサマリーテーブルの表示に使用できる場合は、新しい:recursive:オプションを使用して、パッケージ内のすべてのモジュールを自動的に検出できますが、深くネストされており、すべての属性、クラス、そのモジュールの関数と例外。

ここで私の答えを参照してください:https ://stackoverflow.com/a/62613202/12014259

于 2020-06-29T09:00:23.600 に答える