What does "Title level inconsistent" mean?

Question

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?

Amoakuh

Answer 1

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.

Amoakuh

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. – Monostylous

Also watch out for .. include:: externalfile.txt directives - the adornment hierarchy in that child document must also be consistent with the parent document – Embay

sphinx-doc.org was reorganized. New link to section information. – Lancewood

Answer 2

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

Phonetic

Answer 3

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.

Vendor

Answer 4

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.

Quirinus

Answer 5

For me, it was this:

==
h1
==

...

h3
--

...

h2
==

...

I had to bump up h3 to use = instead of -.

Unpremeditated