How let Sphinx-autoapi show custom comment from source code

Question

In a python project I generate autoapi documntation. Special comment appear in generated html files. For instance it's working and displaying on final html page:

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

Or

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

However I would like autoapi generate some custom comment into html page For example I've got a comment in code like this:

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

But this last comment not shown in generated documentation. Maybe because it hasn't connected to any definition structure in source code? (I mean neither variable declaration nor function or class declaration) Anyway, how should force sphinx to generate html entry from any comments arrounded by triple apostrophe?

Answer 1

There are two options for having sphinx parse variable comments. The first is via attribute docstrings, which are specified in pep 224 to belong below the attribute that they describe, as in your first example. While it was rejected, it is the format sphinx requires in order to work correctly:

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

Renders as:

Alternatively, sphinx will also pick up comments above the attribute that start with a colon and treat them like a docstring, which in some cases looks a bit better in the source code:

#: Description for p_var1
p_var1 = "segg"

Renders also as:

---

There is no option to pick up a comment without a module, exception, class, method, function, or variable being attached to it, becauseautodoc explicitly only considers information from docstrings (and call signatures, but that's the only exception).