7

I'm trying to improve the structure of the documentation of my python modules.

Right now I have an Sphinx index.rst file that looks like this:

Contents:

.. toctree::
:maxdepth: 3

.. automodule:: myModule1
    :members:

.. automodule:: myModule2
    :members:

etc. This produces a HTML page that contains a long chaotic list of all my documented functions. This means that the documentation is easier to read in code, than in its HTML output.

The first improvement is easy: I can add titles and descriptions to the start of each model, so that the visual separation of modules becomes clearer in the html output. So like this:

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""

etc. But now I'd like to take this one step further by separating my modules into sections that have their own section titles and descriptions that belong to a subset of the module's functions. I tried the following:

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""
... # meaning import statements etc
"""
**********************************************
First Section title
**********************************************
Some descriptive text
"""
def myFunction1()
    """ function doc """
    ... # meaning the actual function implementation

def myFunction2()
    """ function doc """
    ... # meaning the actual function implementation

"""
**********************************************
Second Section title
**********************************************
Some descriptive text
"""
def myFunction3()
    """ function doc """
    ...  # meaning the actual function implementation

def myFunction4()
    """ function doc """
    ...  # meaning the actual function implementation

But this leads to a:

'SEVERE: Unexpected section title or transition.'

error when running make HTML.

So how can I get the desired structure without moving documentation away from the code it documents?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
5Ke
  • 1,209
  • 11
  • 28
  • 1
    Sphinx does not allow arbitrary section headers in docstrings. The `sphinx.ext.napoleon` extension is one way to work around that. I'm not sure how much it helps you, but it supports a number of predefined section headers. See http://www.sphinx-doc.org/en/stable/ext/napoleon.html. – mzjn Jun 22 '17 at 17:19
  • 1
    @mzjn `sphinx.ext.napoleon` definitely seems useful, but I'm not able to get it to work with my requested type of sections – 5Ke Jun 23 '17 at 09:02
  • 3
    It is possible to have sections in module-level docstrings. But there can be only one such docstring per module. A module's `__doc__` attribute is the text of the string literal that occurs as the very first statement in the module. See also this rejected Sphinx enhancement suggestion: https://github.com/sphinx-doc/sphinx/issues/442. – mzjn Jun 26 '17 at 10:51

1 Answers1

3

So how can I get the desired structure without moving documentation away from the code it documents?

Stop using automodule and use autoclass/autofunction instead? That way you can craft and reorganise your end document however you want without messing with the Python-level sources, and the docstrings remain the proper source of truth.

Alternatively, split your modules into sub-modules which each gets autodocumented and can have a formatted module-level docstring. Incidentally you probably want to configure autodoc_member_order as it's alphabetical by default (and thus will reorder everything). bysource will show the autodocumented members in whatever order you've written them in your source file.

An other alternative would be to swap the entire thing around and write the modules in literate / doctest form. I don't think there's good standard support for this but doctest might have utility functions which let you convert a "literate document" into something approaching an importable module.

Masklinn
  • 34,759
  • 3
  • 38
  • 57
  • 2
    >Stop using automodule and use autoclass/autofunction instead? That would require me to manually edit documentation while developing my Python module. "Auto" in autodoc suggests that there is some automatic solution. I would be happy if there is something like following: section Constraints - member names that match regex "constr_*", section Formulation - the rest of members. – pdp Jun 15 '22 at 06:16
  • " That would require me to manually edit documentation while developing my Python module" yes. – Masklinn Jun 15 '22 at 06:54
  • ""Auto" in autodoc suggests that there is some automatic solution." auto means you get whatever autodoc gives you, with some customisability. If you want things autodoc can not be configured for... you have to jettison the bits which don't do what you want. – Masklinn Jun 15 '22 at 06:54
  • "I would be happy if there is something like following: section Constraints - member names that match regex "constr_*", section Formulation - the rest of members." then I don't think you will be able to reach nirvana, what do you want me to tell you? All the autodoc options are documented and the source is available, you can go look for yourself. – Masklinn Jun 15 '22 at 07:00