python - 使用 setuptools 为 Python 项目自动生成文档

Question

我创建了一个使用 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和 docstrings 自动生成此文档。

最终，我想为另一个使用 Python C-api 的项目自动生成 apidocs。我找不到任何东西。

我的主要问题是：有没有更简单的方法来自动生成这个文档？

Answer 1

要扩展setup.py它包含 Sphinx 的额外命令，您可以创建自定义命令。我已经编写了一个运行 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 源代码，但这会让你开始。

Answer 2

sphinx-apidoc -F -o source .

将使用 sphinx-quickstart 生成一个项目并递归查找 python 模块

你目前的效率差不多。

===这里只是一厢情愿===

如果你可以调用类似的东西，那不是很可爱

./setup.py build_sphinx -C

它会为您创建 index.RST，读取您敲过的任何 RST 文件，解析所有文档字符串并吐出一些 html。