Question

我刚开始使用Sphinx工具为我的代码生成文档。但我有点困惑，因为它并不像我预期的那么容易。我使用：

创建Sphinx文档

sphinx-quickstart

然后我将我的* .rst文件创建到“source”文件夹中。好像我需要为我想要为其创建文档的每个模块创建一个* .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标志强制覆盖。

狮身人面像，最佳做法

3 个答案: