狮身人面像,最佳做法

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.
        '''