问题标签 [docstring]

所以我查看了一些代码并在 pylint 的帮助下将其提升到 PEP 8 标准，我注意到如果我在打印语句中使用三引号，其中文本超过 120 个字符（我们允许 120 而不是 79）pylint没有抱怨。
这是 pylint 中的一个错误，还是它认为它可能是一个注释并且对行的长度更宽容，或者它不关心你在三引号中使用字符串有多远，因为你可能想以这种方式格式化它们？

为了清楚起见：是的 pylint 在超过行长的所有其他情况下都可以正常工作。

所以我试图创建一个“动态”的文档字符串，它是这样的：

基本上让文档字符串@param animalType显示任何ANIMAL_TYPES内容；这样当这个变量被更新时，文档字符串就会自动更新。

不幸的是，它似乎不起作用。有谁知道是否有办法实现这一目标？

我注意到在大多数情况下，Clojure 多行文档字符串似乎是手动格式化的，包括 clojure.core 中的那些。来自https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj的示例：

这似乎很奇怪，因为这意味着不同的文档字符串将具有不同的换行长度等，需要手动维护。

有没有更好的方法来格式化多行文档字符串？

在 twisted 的源代码中，许多文档字符串包含这样的格式：L{xxx} 或 C{xxx} 或以“@”开头的行，它们的含义是什么？

例如，在 twisted/internet/interfaces.py 中：

L{IPullProducer}、C{resumeProducing}、@type 生产者？

顺便说一句，这些格式是标准 python 文档字符串格式的一部分吗？如果是这样，我应该参考哪里？谢谢 ：）

我很快就开始了一个开源 Python 项目，我正在尝试提前决定如何编写我的文档字符串。显而易见的答案是使用 reStructuredText 和 Sphinx with autodoc，因为我真的很喜欢在我的文档字符串中正确记录我的代码然后让 Sphinx 自动为我构建一个 API 文档的想法。

问题在于它使用的 reStructuredText 语法——我认为它在渲染之前完全不可读。例如：

您必须真正放慢速度并花一点时间从语法混乱中弄清楚。我更喜欢 Google 的方式（Google Python Style Guide），上面的对应物是这样的：

好多了！但当然，Sphinx 将没有这些，而是​​将所有文本呈现Args:在一行之后。

所以总结一下 - 在我去使用这种 reStructuredText 语法污染我的代码库之前，我想知道是否有任何真正的替代方法可以使用它和 Sphinx，而不仅仅是编写我自己的 API 文档。例如，是否有处理 Google Style Guide 的文档字符串样式的 Sphinx 扩展？

我想在 Python 文档字符串的其他地方引用先前记录的函数参数。考虑以下（诚然完全人为的）示例：

有没有一种简单的方法可以使用 Sphinx 标记嵌入参数引用，或者这会自动发生吗？

（我是一个完整的 Sphinx 新手。我一直在扫描 Sphinx 文档，但没有找到这个问题的答案，也没有找到演示正确标记的示例。）

我有一个 Sphinx 格式的文档字符串，我想从中提取不同的部分（参数、返回、类型、rtype 等）以进行进一步处理。我怎样才能做到这一点？

我正在为学校完成一个 Scilab 项目，并根据文档中的这段话为我的所有功能添加了评论：

在函数内部，可以使用第一条注释行，直到第一条指令或空行来为函数帮助提供默认内容。

然而help，当我键入时不显示评论help myfunction。相反，它会在搜索页面上启动帮助浏览器。

有任何想法吗？基本上我正在寻找相当于 Matlab 的“H1 行”和“帮助文本”。

我正在尝试提取 Python 模块中所有文档字符串的开始和结束行号。没有正则表达式有没有一种明智的方法？

How to add docstrings and/or comments to Clojure libaries/namespaces as a whole, i.e. not just to specific functions within the namespace?

I've noticed that the clojure source uses (comment ...) in some places to do this (example), is that recommended?