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?

Answer 1

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.

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