Как 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']