0

I have a comment in my python module that documents several classes that follow, e.g. 

###

# Classes for agents: patients and clinicians

###

class EngagementLadder(transitions.Machine):
    """The state machine for agent states.

In fact there are several such multi-class comments. Each serves to break up the file, together organizing it into related sections.

I would like to see those comments in the generated documentation, perhaps as headers. How to do that?

Note that my question is similar to In Sphinx, how to include docstrings/comments located in a module, but outside of class and methods, but the answer that worked for him---putting it in the module docstring---will not work for me as I want these comments further down the file.

David Bridgeland
  • 525
  • 1
  • 9
  • 16
  • 1
    Would modifying the .rst file be an adequate workaround? It would mean copying the comment and making it compliant with reST syntax, but it might give you the placement and formatting you desire. – Steve Piercy Sep 14 '18 at 23:09
  • 1
    There is no obvious way to do what you want. Sphinx processes docstrings, not comments. Also note that there can be only one toplevel docstring per module. – mzjn Sep 15 '18 at 12:18
  • You know, this inability to process non-docstring comments is really a shame. I've managed to set up sphinx to do a lot with my project... and since I use ``autodoc_member_order = 'bysource'`` I generally get my documentation in the order of my source code. I have places where I group methods by an abstract concept, like ``state transition event handler``. Wouldn't it be great to add section header comments?? – SRinSLC May 04 '21 at 21:42

1 Answers1

0

One method of achieving this is to use dummy variables

I.e. The below will add a section heading

SECTION_A = "SECTION A"
"""Section A contains some useful stuff about my project...

It can span multiple lines...

"""

def foo():
    """Description of foo"""
    pass

#: Section B contains some useful stuff about my project...
#: It can span multiple lines
SECTION_B = "SECTION B"

def bar():
    """Description of foo"""
    pass

Documentation here: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute

sam
  • 1,005
  • 1
  • 11
  • 24