标签: sphinx-napoleon

我想从docstrings自动生成文档到我的代码.我有一些基本类用于存储一些数据:

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    """Object name"""
    version: int = 0
    """int: Object version"""

我的rst档案:

DataHolder
==========

.. autoclass:: data_holder.DataHolder
   :members:

我以不同的方式记录了每个属性以显示差异,这里是输出:

看起来Sphinx无法将该Attributes部分与真实属性连接起来,这就是为什么它无法显示其默认值.

我想要实现的最终输出是对于version定义了docstring 的字段的结果batch.我想显示具有默认值和类型的属性名称,但是从类型注释中获取.看起来Sphinx在这种情况下忽略了类型注释.

我的狮身人面像扩展:

extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.autodoc',
    'sphinxcontrib.napoleon',
]

我该怎么做才能实现这种行为？我找不到这种用例的好例子.

我知道用于构建 Google 风格的文档字符串的语法，例如：

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    """

但是，如果我有一个函数可以根据执行的代码分支返回多种类型怎么办？记录这一点的正确方法是什么？

下面是一个例子。该部分应该放入什么Returns？

def foo(x, y):
    """Dummy function.

    Args:
        x (int): integer
        y (int): integer …

我尝试使用活动和描述性的函数名称，然后我用活动和描述性文本 (!) 记录这些名称。这会生成看起来多余的代码。

python中的简化（但不是那么不切实际）示例，遵循numpy docstring样式：

def calculate_inverse(matrix):
    """Calculate the inverse of a matrix.

    Parameters
    ----------
    matrix : ndarray
        The matrix to be inverted.

    Returns
    -------
    matrix_inv : ndarray
        The inverse of the matrix.

    """
    matrix_inv = scipy.linalg.inv(matrix)
    return matrix_inv

特别是对于 python，我已经阅读了PEP-257和 sphinx/napoleon 示例numpy和 Google 风格的文档字符串。我喜欢我可以为我的函数自动生成文档，但是对于像上面这样的冗余示例，“最佳实践”是什么？是否应该简单地不记录“明显”的类、函数等？“显而易见”的程度当然变得主观......

我想到了开源的分布式代码。多个作者建议代码本身应该是可读的（calculate_inverse(A)比 更好dgetri(A)），但多个最终用户将从 sphinx 样式的文档中受益。

我正在使用NumPyDoc样式的文档字符串来记录Python软件包。我想从'numpydoc'Sphinx扩展名切换到Napoleon，因为我发现它以更紧凑，更易读的方式格式化docstring。但是，它没有在文档顶部列出类的方法，我发现numpydoc具有非常有价值的功能。有谁知道如何在拿破仑手动将其打开？

现在有人以简单的方式将现有项目中的所有文档字符串从reStructured Text转换为Google格式吗？

看起来拿破仑可以做类似的事情,但看起来很复杂,所以我想我以前是否有人这样做过.任何想法将不胜感激.

我有一个开源包，在不同的子模块上有很多类。所有类都有方法fit和transform，并继承fit_transform自 sklearn。所有的类都遵循与副标题参数，属性，注释numpydoc，请参见，和方法的文档字符串，在这里我表fit，transform和fit_transform。我复制一个类的例子：

class DropFeatures(BaseEstimator, TransformerMixin):
    """
    Some description.

    Parameters
    ----------
    features_to_drop : str or list, default=None
        Variable(s) to be dropped from the dataframe

    Methods
    -------
    fit
    transform
    fit_transform
    """

    def __init__(self, features_to_drop: List[Union[str, int]]):

        some init parameters

    def fit(self, X: pd.DataFrame, y: pd.Series = None):
        """
        This transformer does not learn any parameter.

        Verifies that the input X is a pandas dataframe, and that the variables to
        drop …

我收到多个警告，例如：

警告：pyfar.signal.TimeData.times 的重复对象描述，pyfar.classes_audio 中的其他实例，对其中之一使用 :noindex:

但想不通为什么？有人建议我可能在不同的第一个文件中两次包含同一个对象。但我认为情况并非如此。

我尝试根据原始包创建一个最小的工作示例（https://github.com/pyfar/pyfar/tree/develop/docs）：

获取代码

git clone https://github.com/f-brinkmann/pyfar_sphinx_test.git pyfar_sphinx_test
cd pyfar_sphinx_test

制作虚拟环境

conda create --name sphinx_test python<3.9
conda activate sphinx_test
pip install -r requirements_dev.txt
pip install -e .

构建文档

cd docs
make clean
make html

产量

Running Sphinx v3.5.3
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, …

我最近开始向我的项目添加文档，并且我正在尝试遵循 Google 风格指南。我正在使用 Sphinx 生成文档，并使用 Sphinx 扩展拿破仑来弥合 Google 样式指南和 reST 之间的差距。

我在渲染参数和注释时没有问题，但我似乎无法让示例部分渲染代码片段。

class Chicken(object):
      """Animal that lays egg and has feathers

         Note:
             Chickens love to eat feed

         Example:
             chicken.eats(feed)
      """

我还尝试在示例部分使用双冒号。

Example::

我正在使用 sphinx autodoc 扩展和 sphinx.ext.napoleon。我正在遵循 numpydoc 风格指南，因为我认为它比谷歌的更具可读性。但是，我注意到以下我无法解决的问题。

我有以下问题。是否可以允许在参数部分（或返回等）中有一个列表？我想要一些类似的东西：

更新根据 Steve Piercy 的回答，我已经删除了一些初始问题。这是python文件：

class Test:

def f(param_1, param_2):

    r"""
    This is a test docstring.

    Parameters
    ----------
    param_1 : pandas data frame
        This would be really cool to allow the following list and make
        it more readable:

        * **index:** Array-like, integer valued representing
          days. Has to be sorted and increasing.
        * **dtype:** float64. Value of temperature.
        * **columns:** location description, e.g. 'San Diego'
    param_2 : int
        nice number!
    """
    pass

不幸的是，这仍然会导致“This …

我目前正在尝试使用Sphinx实现自动文档创建（使用扩展名sphinx-apidoc和napoleon）。这很好用，但是如果将typehints（PEP484约定）自动添加到params列表中会更好。

我想知道这是否可能。

更具体地说：（从拿破仑的例子）

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

如下所示：

参数列表包含所有参数，但不附加类型。可以手动添加它们，但是当决定更改签名时，这可能会带来将来的问题。

手动添加类型的示例：

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

呈现为：