17

setuptools を使用し、次の構造を持つデモ プロジェクトを作成しました。

project/
 |- pizza/
 |   |- __init__.py
 |   `- margherita.py
 |
 |- README.rst
 |- setup.cfg
 `- setup.py

Sphinx を使用して、このプロジェクトのドキュメントを自動生成しようとしています。これまでのところ、私は試しました：

# Generate a sphinx template
sphinx-quickstart
# Use default settings, except for project name, etc.
sphinx-apidoc -o source .
./setup.py build_sphinx

README、setup.pyおよび docstringを使用して、このドキュメントを自動生成する簡単な方法が必要だと思います。

最終的には、Python C-api も使用する別のプロジェクトの apidoc を自動生成したいと考えています。これについては何も見つかりませんでした。

私の主な質問は: このドキュメントを自動生成する簡単な方法はありますか?

4

2 に答える 2

7

Sphinx 用の追加コマンドを含むように拡張setup.pyするには、カスタム コマンドを作成できます。Sphinx apidoc を実行してドキュメント ソースをビルドする小さな例を作成しました。で定義されているソースのプロジェクト名、作成者、バージョン、および場所setup.pyが使用されます (それらが定義されていると仮定します)。

class Sphinx(Command):
    user_options = []
    description = 'sphinx'

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        # metadata contains information supplied in setup()
        metadata = self.distribution.metadata
        # package_dir may be None, in that case use the current directory.
        src_dir = (self.distribution.package_dir or {'': ''})['']
        src_dir = os.path.join(os.getcwd(),  src_dir)
        # Run sphinx by calling the main method, '--full' also adds a conf.py
        sphinx.apidoc.main(
            ['', '--full', '-H', metadata.name, '-A', metadata.author,
             '-V', metadata.version, '-R', metadata.version,
             '-o', os.path.join('doc', 'source'), src_dir])
        # build the doc sources
        sphinx.main(['', os.path.join('doc', 'source'),
                     os.path.join('doc', 'build')])

次に、コマンドをエントリ ポイント グループに登録する必要がありますdistutils.commands。ここで、コマンドは と呼ばれsphinxます。

from setuptools import setup

setup(
    # ...
    setup_requires = ['sphinx'],
    entry_points = {
        'distutils.commands': [
            'sphinx = example_module:Sphinx'
        ]
    }
)

C ソースがどのように処理されるかはわかりませんが、これで始められます。

于 2014-03-08T18:17:27.467 に答える
3 
sphinx-apidoc -F -o source .

sphinx-quickstart でプロジェクトを生成し、python モジュールを再帰的に探します

あなたは現時点で可能な限り効率的です。

=== 以下、ただの希望的観測 ===

次のように呼び出すことができたら素敵ではないでしょうか

./setup.py build_sphinx -C

index.RST を作成し、ノックした RST ファイルを読み取り、すべての docstring を解析し、html を吐き出します。

于 2014-01-20T10:48:13.407 に答える