What does “Title level inconsistent” mean?

20
votes

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?

4
python-sphinx

4 Answers

28
votes

Apparently the answer was obvious: http://sphinx-doc.org/rest.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.

1
votes

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.

1
votes

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.

1
votes

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