Python Sphinx 自动汇总渲染参数，如 numpy答案

【问题标题】：Python Sphinx autosummary rendering of parameters like numpyPython Sphinx 自动汇总渲染参数，如 numpy
【发布时间】：2021-07-25 04:10:59
【问题描述】：

问题

我正在使用 Sphinx 和自动摘要扩展来使用 numpy 样式的文档字符串记录我的 python 3 项目。

当前渲染

这是我当前的渲染。红框显示了参数和返回的当前布局。

所需的渲染

我想像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

狮身人面像配置

我在 conf.py 文件中包含了自动摘要所需的扩展：

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.napoleon',
              'sphinx.ext.autosummary']
autosummary_generate = True
html_theme = 'pydata_sphinx_theme'

autosummary的使用在这里展示：

.. currentmodule:: modified

.. autosummary::
   :toctree: api/

   modified_main

【问题讨论】：

标签： python python-sphinx autodoc

【解决方案1】：

最可能的问题是您的文档字符串中的 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

    """

您没有包含文档字符串的示例，所以我不能绝对肯定。请编辑您的问题以包含您的文档字符串。

【讨论】：

即使文档字符串中的 reST 格式与 numpy doc 中的格式一致（上面已更新），渲染也没有改变。

【解决方案2】：

我通过深入研究 numpydoc 文档找到了解决方案。在conf.py 中的extension 变量中，将元素sphinx.ext.napoleon 更改为numpydoc。更改后的变量现在看起来像

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

渲染变成

红色框给出了像 numpy 一样的所需渲染。

【讨论】：