CODEWITHSUNDEEP
pythonpython-sphinxrestructuredtextsectionsautodoc
Jonathan
Jonathan

Reputation: 2867

Headings when using autodoc in Sphinx

I have a documentation file that looks like this:

##
H1
##

Blah Blah

**
H2
**
Blah Blah

H3
==

Blah Blah

H4
--

Blah Blah

.. automodule:: lib.X
   :members:

The Python file X.py looks like this:

"""
Another H3
==========

Blah Blah
"""

Lots of stuff

My problem is that the first heading from the module docstring in X.py is rendered in HTML in the same way as the last heading in the original document H4, instead of being rendered as a third level heading. Am I doing something wrong or have I found a problem in Sphinx?

Upvotes: 1

Views: 3915

Answers (2)

bad_coder
bad_coder

Reputation: 12940

I think it's a misconception to include reST structural elements in a docstring, namely Sections (headings) and Transitions (Sphinx should issue a warning if you try). Don't confuse the former with Docstring sections. Both are called sections, but that is where the similarities end.

Because, if you want to include a given module or class in two different .rst files, using autodoc directives, the fixed headings (structural element) inside the docstring may not align with the different hierarchy of headings in the .rst files.

This would create a structural constraint, the .rst file heading hierarchy would depend on the placing of your autodoc directives in it. Conceptually, I think control of structure should depend only on the .rst file.

Plus, the section adornments style once encountered defines a heading level, so different placings of your autodoc directives would end up taking control of the .rst structure. (And lets not forget, if your output is HTML you'll be limited to 6 levels of headings, so using them in docstrings would further limit your structural options in the .rst...)

How does docutils factor into this equation? (mentioned by OP in the comments.)

Don't worry about docutils!! A regular Python developer only needs Sphinx (which entails reST) to write nice documentation. The use of docutils would be to write costum Sphinx extensions, but for the majority of uses stable extensions/directives are already provided.

Upvotes: 2

Apropos
Apropos

Reputation: 866

Pages get parsed independently, without knowledge of the adornment symbols/hierarchy you adopt in other pages. The H1/H2/H3 sequence is simply the order as encountered.

For example, try moving your .. automodule:: chunk from bottom of the documentation file (i.e. 5th heading encountered) to the top (i.e. 1st heading) and it's styling will update.

So the section heading in your Python file gets styled H1 viewed in there... or H5 when embedded into the documentation file.

Upvotes: 1

Related Questions