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

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

1 个答案: