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