标签: numpydoc

在使用numpy样式记录 Python 模块并使用sphinx和numpydoc扩展生成 html 文档时，我偶然发现了一个关于项目符号列表的错误（或功能？）。

In reStructuredText (and sphinx/numpydoc), a single-lined paragraph
    - with an immediately following
    - bullet list
    - is allowed,

but if you have a "long" paragraph,
which may be spanning several lines,
    - a following bullet list
    - results in an `ERROR: Unexpected indentation`.

With a blank line added between the "long" paragraph, which again
may span multiple lines, and the following list,

    - bullet lists
    - work fine again. …

我遇到了与此线程相同的问题.当我构建我的Sphinx文档时,make html我得到了很多这样的警告

None:None: WARNING: toctree contains reference to nonexisting document u'cars.Car.time_elapsed'

我在用html_theme = 'sphinx_rtd_theme'.如果我改成它classic,那么我没有得到警告.如果我想补充numpydoc_show_class_members = False到conf.py,那么我不明白他们要么.

但; 我非常喜欢sphinx_rtd_theme,当我使用classic或添加时numpydoc_show_class_members = False,我的Python方法的' TOC '被删除(参见此图像上的红色框),我更喜欢留下.

该cars模块的文档由

.. automodule:: cars
   :members:

该模块包含一个Car具有两种方法的类.文档字符串是用来写的numpydoc.

我正在使用 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 …

我有numpydoc 样式的文档字符串：

def foobar(filename, copy, dtype, iterable, shape, files):
    """
    foobar is 42.

    Parameters
    ----------
    filename : str
    copy : bool
    dtype : data-type
    iterable : iterable object
    shape : int or tuple of int
    files : list of str

    Returns
    -------
    foobarfoo : int
    """
    pass

是否可以检查文档字符串类型是否正确？

（附带问题：numpy 可以返回/打印它发现的函数签名吗？）

例如，我希望以下内容失败：

返回类型

def foobar():
    """
    Returns
    -------
    blub : int
    """
    return "foo"

或者

def foobar(a, b):
    """
    Parameters
    ----------
    a : number
    b : number

    Returns
    ------- …

我正在为一个包开发文档，当我构建 sphinx 文档时，我得到了双冒号

对于每个函数定义的所有字段。

我的文档字符串使用 numpydoc 样式，这些文档中没有冒号来指示它们可能来自哪里：

    """

    Function description

    Parameters
    -----------
    param1: str or list
        A description for the parameter

    Returns
    -----------
    Dictionary
        Some info about what is returned

    Examples
    -----------
        >>> output = somefunction(param1)

    """

以前有人遇到过这个吗？值得注意的是，这种情况不会发生在Examples现场。只是Parameters，，Returns和Return Type。

在numpydoc文档字符串中输入 a listof 的正确方法是什么？int

int[]例如，这个语法有效吗？

def my_function(numbers):
    """
    Parameters
    ----------
    numbers : int[]
        List of numbers
    """

    return numbers

几天前我开始使用 Sphinx 来记录一个 python 包，我得到了一个似乎是常见的错误，但我找不到解决方案。

我使用 sphinx-quickstart 来设置一切。我使用“doc/”作为文档根位置。包含我的包的文件夹设置为：

myfolder/
    doc/
    mypackage/
        __init__.py
        moprob.py
        ...

快速启动后，我将 conf.py 中的路径编辑为：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

然后我将包中的一个脚本添加到 index.rst 以查看 sphinx 是如何工作的。

 .. toctree::
   :maxdepth: 2
   :caption: Contents:

   mypackage/moprob

我得到的错误代码：

.../index.rst:9: WARNING: toctree contains reference to nonexisting document u'mypackage/moprob'

我尝试过的解决方案：

1. 将 sphinx.ext.napoleon 添加到扩展列表中，因为我的所有文档字符串都是使用 numpy 格式编写的。错误并没有消失。我还将拿破仑扩展名放在 autodoc 之后，因为其中一个帮助页面建议了这一点。

   扩展 = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

2. 将 numpydoc_show_class_members = False 添加到 conf.py。我把它直接放在扩展下面。这也没有帮助。

3. 文件夹位置的几种不同配置。我还尝试将根位置设置为 myfolder，将源设置为 mypackage，将构建设置为 doc。没有一个奏效。

你有什么想法可以帮助我吗？

我正在按照 numpy 文档字符串指南编写文档字符串。然后我使用 sphinx 的 autodoc 生成我的文档。在一些文档字符串中，我使用 LaTeX 公式（sphinx.ext.mathjax）。似乎这\r意味着一些特殊的事情，比如一条新线。如果我有以下命令：

"""
This :math:`\langle a, b\rangle` denotes the dot product of a and b
"""

它无法正确渲染。它将类似角度放入新行并给我一个错误：内联解释文本或短语引用起始字符串没有结束字符串 如果我用 \langle 替换 \rangle 一切正常。我怎样才能解决这个问题？

使用autodoc时是否可以禁用完整的自动摘要？

我有一个派生自Python 标准库类的类，它有许多公共方法。我的自定义类应该作为包装器，直接提供使用其协议与我的设备进行通信的方法。因此，我只想在自动摘要表中包含一些选定的继承方法。

.. autoclass:: my_module.MyClass
   :members:
   :show-inheritance:

   .. autosummary::
      my_method
      another_method

该..autosummary::块完全符合我的要求，但..autoclass::会自动创建完整的方法表。有没有办法禁用此功能？

编辑（澄清）

直接使用autosummary指令，我可以生成一个仅包含my_method和 的方法表another_method：

.. autosummary::
   my_method
   another_method

但是，当使用autoclass或automodule 而不使用以下自动摘要指令时，我仍然会得到一个方法表，该方法表看起来与上面的自动摘要块创建的方法表一模一样，只是包含所描述的所有方法：

.. autoclass:: my_module.MyClass
   :members:
   :show-inheritance

编辑2

“完整”自动摘要表由numpydoc生成。