NumPy如何将docstrings处理成参数的sphinx文档？

Question

我想使用sphinx构建我们的文档,并获得与NumPy文档相同的参数格式(https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)

我发现有两种方法可以用sphinx记录第一种样式的参数,其中一种是

:param name: description

要么

:keyword name: description

和另一个(这是NumPy风格)

Parameters
----------
name: type
    description

以下是一个示例:

http://docs.scipy.org/doc/numpy/reference/distutils.html#module-numpy.distutils

和来源

def get_subpackage(self,subpackage_name,
                   subpackage_path=None,
                   parent_name=None,
                   caller_level = 1):
    """Return list of subpackage configurations.

    Parameters
    ----------
    subpackage_name: str,None
        Name of the subpackage to get the configuration. '*' in
        subpackage_name is handled as a wildcard.
    subpackage_path: str
        If None, then the path is assumed to be the local path plus the
        subpackage_name. If a setup.py file is not found in the
        subpackage_path, then a default configuration is used.
    parent_name: str
        Parent name.
    """

但是,当我使用sphinx(我正在使用sphinx-apidoc和sphinx-build)构建文档时,我可以在使用第一种语法(:param name:description)时生成格式化列表,但是当我尝试使用NumPy时风格我没有格式化.看一下rst语法(http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections)似乎就像

Parameters
----------

只是一个部分标题.但是使用sphinx的这种格式,标题参数不会出现在输出中,并且它不会获得任何参数部分格式.

有谁知道NumPy如何使用sphinx构建文档以使这种格式适用于参数？

我试着看看makefile和conf.py,我只是不确定如何

Answer 1

NumPy使用自定义Sphinx扩展:https://pypi.python.org/pypi/numpydoc.

你可以安装它

pip install numpydoc

然后通过添加到扩展名列表将其添加到sphinx conf.py文件中

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'numpydoc']