26

I've been getting warnings in my documentation builds of the variety "Title level inconsistent". As far as I can tell, I have a consistent structure that looks something like:

Big Title
=========

Section
-------

Subsection
~~~~~~~~~~

but the error is associated with autogenerated (automodapi) text that I can't track down:

Classes
^^^^^^^

How can I figure out where the "inconsistency" is coming from?

keflavich
  • 18,278
  • 20
  • 86
  • 118

4 Answers4

39

Apparently the answer was obvious: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

I had been using ==== as my top-level heading because that's what riv.vim does, but #### and **** are above them. ~~~~~ apparently isn't even official.

I still don't fully understand the problem, since I was using ---- above the locations that nominally were using ^^^^, which should be fine, but bumping all the headings up one level has solved my particular problem.

Laurent LAPORTE
  • 21,958
  • 6
  • 58
  • 103
keflavich
  • 18,278
  • 20
  • 86
  • 118
  • 1
    the marker itself does not matter. If you have docs with two or more heading levels, and you use different markers for the same level, then the error occurs. Markers must be consistent at their level. It occurs more often with three or more levels where you have something like `= - ^` for levels 1, 2, 3, as well as `= - +` in the same file. – Steve Piercy Feb 28 '22 at 00:35
  • 2
    Also watch out for `.. include:: externalfile.txt` directives - the adornment hierarchy in that child document must also be consistent with the parent document – Apropos Jun 01 '22 at 02:20
  • sphinx-doc.org was reorganized. [New link to section information.](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html?highlight=sections#sections) – Jake Stevens-Haas Jul 14 '22 at 21:44
3

I had the same trouble, and it seems to me that you should not do a hole in your hierarchy. It is OK for html and Markdown to use any headers you want, but in the rst you have to use all levels.

I mean you could do

h1 h2 h3 h4

or

h2 h3

but you can't do the following

h1 h2 h4

Anton Chevychalov
  • 161
  • 1
  • 2
2

Check the entire document and ensure that you're consistently using the same character to represent each level of hierarchy.

For example, ensure your sections (=), subsections (-), and subsubsections (~) are consistently using the same underline character across the entire document, and that you aren't using different underline characters for the same heading level by accident.

Adil B
  • 14,635
  • 11
  • 60
  • 78
1

I did get the same error that you reported. To me it seems that it was caused by mixing ^ and ~ for subsubsections. By substituting one for the other in the whole document the error disappeared.

Per Westling
  • 13
  • 5