标签: numpydoc

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

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 样式的文档中受益。

这里的主要问题是哪里（如果）有objects.invTensorFlow 的，但是一个如何实际使用它的例子会很好。

例如，我目前有以下文档字符串：

"""
Load the weights of a model stored in saver.

Parameters
----------
checkpoint_dir : str
    The directory of checkpoints.
sess : tf.Session
    A Session to use to restore the parameters.
saver : tf.train.Saver
"""

如何使用 intersphinx 自动将对象链接到 TensorFlow 文档？

我正在使用带有 numpydoc 扩展和自动摘要的 sphinx。经过一些实验，我将以下选项添加到我的 conf.py 文件中。

autosummary_generate = True
numpydoc_show_class_members = False

这为我引用的每个类提供了一个新文件，如下所示，它还创建了所有属性和方法的汇总表。

.. autosummary::
   :toctree: generated/
   :nosignatures:

   MyClass

问题是，虽然文档字符串的第一行有一个方法的摘要表，但方法的名称没有链接到任何内容。如何获取方法的文档字符串来创建自己的文件（或者至少在与类相同的文件中生成文档）？

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

我正在开发一个需要Numpy文档的项目.在我的Java时代,我记得在Eclipse/IDEA中检查过Javadoc遵从性的linters; 有没有相当于检查Numpy文档样式的依从性？

我知道PEP257,但似乎没有对Numpy文档进行任何具体检查.

我在让 sphinx 创建模块汇总表时遇到问题。我已添加sphinx.ext.autosummary到我的conf.py文件中并且正在使用numpydoc. Sphinx 似乎为类上的属性和方法创建汇总表，但它不会为包含该类的模块创建汇总表。

我创建了一个最小工作示例（MWE）来测试这一点。MWE 项目只有一个__init__.py和 ，它导入generic_module. 其内容为generic_module：

def foo(a, b):
    """
    Adds a + b
    """
    return(a+b)

def bar(a, b):
    """
    Subtracts a + b
    """
    return(a-b)

class onetwo(object):
    """
    Adds 1 or 2
    """
    def __init__(self):
        self.whatever = 1

    def one(self, a):
        """
        Adds one to a
        """
        return(a + 1)

    def two(self,a):
        """
        Adds two o a
        """
        return(a + 2)

Sphinx 自动文档foo …

我有一个开源包，在不同的子模块上有很多类。所有类都有方法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 …

我无法使 Sphinx 使用 numpy 格式正常工作。我正在使用此示例进行测试，执行“make html”，但我收到一些警告以识别参数、注释、返回等。例如：

SEVERE: Unexpected section title.
ERROR: Unexpected indentation.
also
WARNING: Inline emphasis start-string without end-string.
WARNING: Literal block expected; none found

这个问题已经被问过，但经过几个小时的搜索和尝试后我没有成功。

到目前为止我所做的：

• 安装Sphinx v1.3.5
• 更新numpydoc至0.5版本
• 将扩展名numpydoc、sphinxcontrib.napoleon和添加sphinx.ext.napoleon到文件中conf.py。
• 尝试过 rst2html docum.txt docum.html
• 因为我认为它没有使用 numydoc，所以我写了一个不正确的名称作为扩展名，并且它给出了一个错误（应该是这样，所以我认为它正在识别 numpydoc）。
• 添加numpydoc_show_class_members = False到conf.py
• 删除之前的整个 html 输出

有什么问题的建议或提示吗？我可以尝试什么？

谢谢

我正在尝试使用 numpy 文档字符串格式记录元组返回值，但无法使其与 pycharm 类型提示一起使用。

我尝试了多种方法，甚至找到了一种适用于该类型的方法，但不允许我为其每个元素添加描述。

要记录的函数示例：

def function():
    foo = 42
    bar = {
        example : 1337,
        dictionary : 46,
    }
    return foo, bar

现在，我可以记录它的一种方法是：

def function():
    """
    This is the function summary.

    Returns
    -------
    foobar : tuple[int,[dict[string, int]]
        This is a description of the return type
    """
    foo = 42
    bar = {
        'example' : 1337,
        'dictionary' : 46,
    }
    return foo, bar

这将为我提供描述和正确的返回类型提示，但不是每个元素的单独描述，这是我想要的。

这是我想要实现的目标的一个非工作示例：

def function():
    """
    This is the function summary.

    Returns
    -------
    foo : int …

Numpy 文档字符串指南说：

冒号前面必须有空格，如果类型不存在，则省略。

并举了一个例子：

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)

另一方面， PEP8字面意思是冒号前的空格是错误的：

# Wrong:

code:int  # No space after colon
code : int  # Space before colon

我知道这适用于代码，而不适用于文档字符串，但为什么不保持一致？

题

在冒号前放置一个空格的动机是什么？

它似乎违反了排版规则和 python 约定（或至少是直觉）。