如何让 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"

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

Answer 1

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

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

呈现为：

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

#: Description for p_var1
p_var1 = "segg"

也呈现为：

没有附加模块、异常、class、方法、函数或变量的评论，因为autodoc明确地只考虑信息from docstrings（和调用签名，但这是唯一的例外）。

How let Sphinx-autoapi show custom comment from source code