Sphinx，最佳做法

| 我刚刚开始使用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文件。谢谢。

已邀请:

3 个回复

钾涎净介

没有更简单的方法。 Sphinx不是像epydoc这样的API文档生成器，而是专注于手写文档。因此，您需要手工编写许多文档。优点是，您还可以编写API文档以外的文档（例如，教程，使用指南，甚至最终用户文档），并且可以逻辑地构造API文档，而不仅仅是可用对象的简单字母列表。如果正确完成，则此类文档通常更容易理解和使用。查看知名项目的文档（例如Werkzeug或Sphinx本身），以了解一些最佳做法。

抢垢洛韧

快速记录您的应用程序的一种简单方法是按照常规方式仅将docstring写入类和方法，然后在.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.
        \'\'\'

炉挤仙挟

您可以使用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不会修改现有文件，您可以使用“ 10”标志强制覆盖。

要回复问题请先登录或注册

Sphinx，最佳做法

3 个回复

发起人

python

python_sphinx

问题状态

Sphinx，最佳做法

与内容相关的链接

3 个回复

发起人

python

python_sphinx

问题状态