Python 像 numpy 这样的参数的 Sphinx 自动摘要渲染
Python Sphinx autosummary rendering of parameters like numpy
问题
我正在使用 Sphinx 和自动摘要扩展来记录我的 python 3 带有 numpy 样式文档字符串的项目。
当前渲染
这是我目前的效果图。红色框显示参数和 returns.
的当前布局
需要渲染
我想更改参数的布局，returns 像 numpy 一样，如下面所需的渲染示例所示，以便参数名称和类型在一行，描述在另一行缩进。
我该如何实现？ （查看 numpy、scipy 和 pandas 文档，我找不到他们为更改渲染做了什么特别的事情。）
Numpy stype 文档字符串
代码中的文档字符串为：
def modified_main(raw_img_path, ground_truth_img_path, ground_truth_count=None, sort=True):
"""
Computes deviation of thresholded images using different methods
compared to user input ground truth image.
Parameters
----------
raw_img_path : str
Path of raw image.
ground_truth_img_path : str
Path of ground truth image.
ground_truth_count : int, optional
User input ground truth cell count.
sort : bool, optional
Sort the deviation by majority vote.
Returns
-------
optimal_method : str
Optimal threshold method.
optimal_threshold : float
Threshold given by optimal threshold method.
"""
pass
Sphinx 配置
我在 conf.py 文件中包含了自动摘要所需的扩展：
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.autosummary']
autosummary_generate = True
html_theme = 'pydata_sphinx_theme'
这里显示了自动摘要的使用：
.. currentmodule:: modified
.. autosummary::
:toctree: api/
modified_main
最有可能的问题是您的文档字符串中 reST 的格式与 empty 的格式不相似。
def empty(shape, dtype=None, order='C'):
"""Return a new matrix of given shape and type, without initializing entries.
Parameters
----------
shape : int or tuple of int
Shape of the empty matrix.
dtype : data-type, optional
Desired output data-type.
order : {'C', 'F'}, optional
Whether to store multi-dimensional data in row-major
(C-style) or column-major (Fortran-style) order in
memory.
See Also
--------
empty_like, zeros
.. snip
"""
您没有包含文档字符串示例，所以我不能绝对确定。请编辑您的问题以包含您的文档字符串。
我通过深入研究 numpydoc 文档找到了解决方案。在 conf.py 中的 extension 变量中，将元素 sphinx.ext.napoleon 更改为 numpydoc。更改后的变量现在看起来像
extensions = ['sphinx.ext.autodoc',
'numpydoc',
'sphinx.ext.autosummary']
渲染变成
其中红色框给出了像 numpy 一样的所需渲染。
问题
我正在使用 Sphinx 和自动摘要扩展来记录我的 python 3 带有 numpy 样式文档字符串的项目。
当前渲染
这是我目前的效果图。红色框显示参数和 returns.
的当前布局需要渲染
我想更改参数的布局，returns 像 numpy 一样，如下面所需的渲染示例所示，以便参数名称和类型在一行，描述在另一行缩进。
我该如何实现？ （查看 numpy、scipy 和 pandas 文档，我找不到他们为更改渲染做了什么特别的事情。）
Numpy stype 文档字符串
代码中的文档字符串为：
def modified_main(raw_img_path, ground_truth_img_path, ground_truth_count=None, sort=True):
"""
Computes deviation of thresholded images using different methods
compared to user input ground truth image.
Parameters
----------
raw_img_path : str
Path of raw image.
ground_truth_img_path : str
Path of ground truth image.
ground_truth_count : int, optional
User input ground truth cell count.
sort : bool, optional
Sort the deviation by majority vote.
Returns
-------
optimal_method : str
Optimal threshold method.
optimal_threshold : float
Threshold given by optimal threshold method.
"""
pass
Sphinx 配置
我在 conf.py 文件中包含了自动摘要所需的扩展：
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.autosummary']
autosummary_generate = True
html_theme = 'pydata_sphinx_theme'
这里显示了自动摘要的使用：
.. currentmodule:: modified
.. autosummary::
:toctree: api/
modified_main
最有可能的问题是您的文档字符串中 reST 的格式与 empty 的格式不相似。
def empty(shape, dtype=None, order='C'):
"""Return a new matrix of given shape and type, without initializing entries.
Parameters
----------
shape : int or tuple of int
Shape of the empty matrix.
dtype : data-type, optional
Desired output data-type.
order : {'C', 'F'}, optional
Whether to store multi-dimensional data in row-major
(C-style) or column-major (Fortran-style) order in
memory.
See Also
--------
empty_like, zeros
.. snip
"""
您没有包含文档字符串示例，所以我不能绝对确定。请编辑您的问题以包含您的文档字符串。
我通过深入研究 numpydoc 文档找到了解决方案。在 conf.py 中的 extension 变量中，将元素 sphinx.ext.napoleon 更改为 numpydoc。更改后的变量现在看起来像
extensions = ['sphinx.ext.autodoc',
'numpydoc',
'sphinx.ext.autosummary']
渲染变成
其中红色框给出了像 numpy 一样的所需渲染。