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 lik

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

Answer 3

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.