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

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

Answer 1

[sphinx解析变量注释有两个选项。第一个是通过属性文档字符串，在您的第一个示例中，该属性在pep 224中指定为属于它们描述的属性之下。当它被拒绝时，它是sphinx才能正常工作所需的格式：

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

渲染为：

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

#: Description for p_var1
p_var1 = "segg"

渲染也为：

---

[没有选择，而没有附加模块，异常，类，方法，函数或变量的注释，因为autodoc明确仅考虑信息from docstrings（和调用签名，但这是唯一的）例外）。