python-3.x - 如何让 Sphinx-autoapi 从源代码中显示自定义注释

Question

在 python 项目中，我生成 autoapi 文档。特殊注释出现在生成的 html 文件中。例如，它正在工作并显示在最终的 html 页面上：

def do_action(self,params):
  """
  This is function to do some cool stuffs.
  Actually it should
  """
  pass

或者

...
applicationConfig = None
"""This variable hold some important data"""

但是我希望 autoapi 在 html 页面中生成一些自定义注释例如我在这样的代码中有一个注释：

"""These are public variable:"""
p_var1 = "segg"
p_var2 = "fos"

但是最后一条评论没有显示在生成的文档中。也许是因为它没有连接到源代码中的任何定义结构？（我的意思既不是变量声明，也不是函数或类声明）无论如何，应该如何强制 sphinx 从由三重撇号包围的任何注释中生成 html 条目？

标签： python-3.xpython-sphinx

Answer 1

sphinx解析变量注释有两种选择。第一种是通过属性文档字符串，在pep 224中指定它们属于它们描述的属性，如在您的第一个示例中。虽然它被拒绝了，但它是sphinx正常工作所需的格式：

p_var1 = "segg"
"""Docstring for p_var1"""

呈现为：

或者，sphinx还将选取以冒号开头的属性上方的注释并将它们视为文档字符串，在某些情况下，在源代码中看起来更好一些：

#: Description for p_var1
p_var1 = "segg"

也呈现为：

---

如果没有附加模块、异常、类、方法、函数或变量，则无法选择评论，因为autodoc显式只考虑来自文档字符串的信息（和调用签名，但这是唯一的例外）。