This appears in the TOC as a level above "Plotting", so I think needs a lower decoration level:

https://10464-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/axes_api.html

I tried to change the header hierarchy without checking the result... and I see now that didn't work and that I didn't know how headers works in rst. I tried to lower the subplot level and that level stayed the same but everything else toggled its level... Tries again.

edit: I thought I pushed a new version yesterday but something went wrong. It should be updated now.

I don't think this is going the right way. This whole page was documenting theAxes class. You've now changed it to theaxes module and inserted the subplots stuff in between the class description and the list of functions (the sections here are used to group theAxes methods by topic).

It may be ok to document the completeaxes module here, but then one would have to change the structure. The TOC is currently "within the class" and only listing its functions.

It would have to go to the top and be restructured to something like:

• Axes
  • Plotting
  • ...
• Subplots

But why should there be a special page for documenting the Axes class instead of the axes module?

But the page can of course be restructured in same way.

TheAxes class is so large and fundamental, that it might have a dedicated page. But I'm not saying it has to be that way. I also laid out a possible structure if the file should contain the whole module.

I am not sure what is the best. Your structure is of course a possibility (it was not in your post when I wrote my answer).

I am thinking that axes is one module, it consist of 2 public classes and a factory function. Most axes used in practice are also subplots. The suggest structure show the 2 classes and the factory function at the beginning in a way that don't take up to much place and I doubt that the order is confusing.

What about changing the name tosubplot sub module or something like that?

One problem is that the axes module is not included in the module list in neither version of the documents.