标签: docstring

我正在使用spyder和对象检查器进行大量工作,我发现这是一个非常方便的即时帮助功能.一些模块似乎从这个功能中获益非常好.例如,一个非常基本的numpy函数(numpy.absolute)在对象检查器中生成以下视图:

我想知道,我怎么能用这样的方式编写自己的模块,当我在spyder中调用我的函数时会产生这样一个很好的视图.

我目前已经安装了 VS Code 作为 Jupyterlab 的替代编辑器，用于 Python 数据科学开发。现在我想知道如何显示函数的文档字符串或签名？

我没有发现任何有关需要更改设置的快捷方式的信息。

我使用VS Code作为编辑器，使用autoDocstring作为Python的自动文档字符串生成器扩展。有时我会通过引入新参数或修改它们的名称、默认值等来修改函数的参数。在这种情况下，我需要对文档字符串进行手动更改。

当我更改函数签名时，有什么方法可以自动更新文档字符串吗？至少在文档字符串部分引入了新参数。

为字典参数添加docstring的推荐方法是什么？我可以在这里看到多行doc-string示例.

我需要在docstring中记录函数的输入参数.如果它是一个简单的变量,我可以使用类似的东西:

 def func2(a=x, b = y):
 """ fun2 takes two integers 

 Keyword arguments:
 a -- refers to age (default 18)
 b -- refers to experience (default 0)
 """

如果我们dict作为输入参数传递给函数:

 def func3(**kwargs):
     """ takes dictionary as input

      <Here how to explain them - Is it like?> 
      kwargs['key1'] -- takes value1

      <or simply>
      key1 -- takes value1
      """

我想为自己创建一个新模块,但我也想让一些同事能够使用它.我开始用英语编写我的文档字符串,但后来我意识到,对于那些不太了解这种语言的人来说,它会使模块变得无用.

我的第一个想法是键入英语和同一文档字符串,西班牙语.但这似乎不对,如果我想让一些俄罗斯朋友也使用它呢？如果我有朋友在世界各地有朋友没有任何共同语言阅读文档怎么办？

在多种语言中编写然后阅读文档字符串的最简单方法是什么？

我正在尝试使用 pydocstyle 检查我的文档字符串的质量，但出现此错误：

D205: 1 blank line required between summary line and description (found 0)

这是我的代码的样子

def func(input):
    """

    Function that does something interesting.
        Args:
            -input- Input of the function

    Returns:
        output- Output of the function

    """
    data = words + sentences
    corpus= somefunction(data)

当我在文档字符串和函数语句之间添加一个空行时；

def func(input):
    """

    Function that does something interesting.
        Args:
            -input- Input of the function

    Returns:
        output- Output of the function

    """

    data = words + sentences
    corpus= somefunction(data)

我得到这个错误：

D202: No blank lines allowed after …

我发现这真的很烦人，快速文档没有显示属性，列在类的文档中。我认为原因是不正确或不受支持的文档字符串格式，但是reST和Google样式的行为是相同的（我在 中正确设置了它们Python Integrated Tools）。

我目前的文档字符串样式是Google. 让我来看看图片中有什么问题：

这里是Actor课。 如您所见，Attributes部分出现在文档字符串中，但不在快速文档弹出窗口中。

此外，属性上没有注释world_id。

Args的__init__认识就像一个魅力。

让我们将 docstring 直接添加到属性（在answer 中是如何建议的）。效果很好，不是吗？

并在另一个方法中调用属性的快速文档。哇，又没有描述了。

如何让事情发挥作用？如何设置 PyCharm 使其赶上类的属性并在快速文档中显示它们？

PyCharm 2018.2.4（社区版）。Ubuntu 16.04。

我知道用于构建 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 …

对于pydocstyle错误代码D401阅读：First line should be in imperative mood。

我经常遇到这样的情况，我写了一个文档字符串，我的 linter 抛出了这个错误，然后重写了它——但这两个文档字符串在语义上是相同的。为什么对 docstrings 有必要的情绪很重要？

我目前正在使用 Sphinx 记录我的 Python 项目。在文档字符串的多行部分中包含项目符号列表时，我遇到了一个问题。

我想包括一个项目符号列表，但其中一项很长。我想要：

• 通过 Sphinx 正确呈现项目符号列表
• 但也有我的代码尊重 PEP8 关于行长度（<79）

你有什么建议让我为这个文档字符串做些什么：

class geography():
""" Class defining a geography (cities and distance matrix)

This class implements a geography with a list of named cities with their
associated coordinates in a plane. Helper functions enable to :

- give a visual representation of that geography
- give a visual representation of the distance matrix
- give a visual representation of a configuration, a configuration being the repartition of some or …