NumPy如何将文档字符串处理为sphinx文档中的Parameters? [英] How does NumPy process docstrings into sphinx documentation for Parameters?

问题描述

我想使用狮身人面像构建我们的文档，并在参数上获得与NumPy文档相同的格式(

I want to build our documentation using sphinx and get the same formatting on parameters as the NumPy docs ( https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt )

我发现了两种通过狮身人面像以这种第一种样式记录参数的方法，一种是

I have found two ways to document parameters in this rst style with sphinx, one which is

:param name: description

或

:keyword name: description

和另一个(NumPy样式)

and the other (which is the NumPy style)

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

这是一个看起来像这样的例子:

Here is an example of what that looks like:

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样式我没有得到格式.查看第一种语法( http://docutils.sourceforge.net/docs /ref/rst/restructuredtext.html#sections )，似乎类似

However, when I build the docs with sphinx ( I am using sphinx-apidoc and sphinx-build ), I can generate the formatted lists when I use the first syntax ( :param name: description), but when I try to use the NumPy style I do not get the formatting. Looking at the rst syntax ( http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections ) it seems that something like

Parameters
----------

只是部分标题.但是，将这种格式与sphinx一起使用时，标题Parameter不会出现在输出中，并且不会获得任何参数节的格式.

is just a section title. But using this formatting with sphinx the title Parameter does not appear in the output, and it gets none of the parameter section formatting.

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

Does anyone know how NumPy builds the documentation with sphinx to get this sort of formatting to work for parameters?

我尝试查看makefile和conf.py，但我不确定如何操作

I have tried to look at the makefile and conf.py, and I'm just not sure how

推荐答案

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

NumPy uses a custom Sphinx extension: https://pypi.python.org/pypi/numpydoc.

您可以通过安装它

pip install numpydoc

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

and then you add it to the sphinx conf.py file by adding to the extensions list

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

这篇关于NumPy如何将文档字符串处理为sphinx文档中的Parameters?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！