Как NumPy обрабатывает docstrings в документацию sphinx для параметров?

Я хочу создать нашу документацию с помощью sphinx и получить то же форматирование параметров, что и NumPy docs (https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)

я нашел два способа документировать параметры в этом первом стиле со сфинксом, один из которых

:param name: description

или

:keyword name: description

и другой (который является NumPy style)

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, я не получаю форматирование. Взгляд на первый синтаксис ( http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections) кажется, что-то вроде

Parameters
----------

- это просто название раздела. Но при использовании этого форматирования с sphinx параметр title не отображается в выходных данных и не получает форматирование раздела параметров.

кто-нибудь знает, как NumPy строит документацию со сфинксом, чтобы получить такое форматирование для работы с параметрами?

Я попытался посмотреть на makefile и conf.py, и я просто не уверен, как

1 ответов


NumPy использует пользовательское расширение Sphinx:https://pypi.python.org/pypi/numpydoc.

Вы можете установить его с

pip install numpydoc

и затем вы добавляете его к Сфинксу conf.py файл путем добавления в список расширений

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