Я хочу создать нашу документацию с помощью sphinx и получить такое же форматирование параметров, как и в документации NumPy (https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)
Я нашел два способа документировать параметры в этом первом стиле с помощью sphinx, один из которых
:param name: description
or
: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 стиль форматирования не получаю. Рассмотрим первый синтаксис (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections) кажется, что что-то вроде
Parameters
----------
это просто заголовок раздела. Но при использовании этого форматирования с помощью sphinx заголовок Parameter не отображается в выводе, и он не получает никакого форматирования раздела параметров.
Кто-нибудь знает, как NumPy создает документацию со сфинксом, чтобы такое форматирование работало для параметров?
Я попытался посмотреть makefile и conf.py, но я просто не уверен, как