Sphinx，最佳实践

Question

我刚刚开始使用 Sphinx 工具为我的代码生成文档。但我有点困惑，因为它并不像我想象的那么容易。我使用以下命令创建 Sphinx 文档：

sphinx-quickstart

然后在“source”文件夹中创建 *.rst 文件。似乎我需要为每个要为其创建文档的模块创建一个 *.rst 文件。对于 test.py，我创建 test.rst。在 test.rst 中，我有：

.. automodule:: test
    :members:
    :show-inheritance:

然后在 test.py 中，我有：

"""
.. module:: test
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

然后我使用以下方法生成文档：

sphinx-build -b html source/ build/

一切都按预期工作，但问题是它并不像我预期的那么容易。我想一定有一种更简单的方法可以跳过其中一些步骤。我想知道是否有任何方法可以为包内的所有模块生成文档，而不是为每个模块生成 *.rst 文件。

谢谢。

Answer 1

没有更简单的方法了。 Sphinx 不是像 epydoc 那样的 API 文档生成器，而是专注于手写文档。因此，您需要手写大量文档。

优点是，您还可以编写 API 文档之外的文档（例如教程、使用指南，甚至最终用户文档），并且您可以逻辑地构建 API 文档，而不仅仅是可用对象的简单字母顺序列表。如果做得正确的话，这样的文档通常更容易理解并且更容易使用。

查看知名项目的文档（例如 Werkzeug 或 Sphinx 本身）查看一些最佳实践。

Answer 2

快速记录应用程序的一种简单方法是像往常一样将文档字符串写入类和方法中，然后根据需要在 .rst 文件中补充它们。

template.rst:

Templating
----------
Notes about templating would go here.

.. automodule:: myapp.lib.template
    :members:
    :undoc-members:

    .. py:attribute:: filepath

        Full path to template file. This attribute is added in runtime, so
        it has to be documented manually.

myapp/lib/template.py:

class Template(object):
    '''
    Class for rendering templates.

    Usage example::

        >>> t = Template('somefile')
        >>> document = t.render(variables={'ID': 1234})

    Rendered document is always returned as a unicode string.
    '''

    def render(self, **args):
        '''
        Render template. Keyword arguments are passed `as-is` to renderer.
        '''

Answer 3

您可以使用 sphinx-apidoc 为您创建 rst 文件。

sphinx-apidoc -o outputdir pythondir

运行输出示例：

% sphinx-apidoc -o source/ ../
File source/module1.rst already exists, skipping.
File source/module2.rst already exists, skipping.
Creating file source/module3.rst.

rst docs updated in source/.

sphinx-apidoc 不会修改现有文件，您可以使用 -f 标志强制覆盖。