Currently, if you include the option show-module-summary, then for themes with contents sidebars (such as jupyter-book), then the lack of a new header before the full module contents docs (i.e. after the last module summary section) means that the page's hierarchy is mis-represented.
For example, take the following module, containing a class, attribute and function:
Here we can see the right-hand sidebar displays the contents as one would expect, with each docs entry being a new section in the contents.
However, if we turn on module summaries, we get the following:
Here we can see that the docs entries are displayed as being contents within the last of the module summary sections (in this case Attributes, rather than being listed either as at the same hierarchy as the summary sections, or within a new section, thereby indicating they're not within Attributes.
I'm not sure what the preferred fix for this would be, but probably the most consistent thing would be to move the summary sections into a section above Module Contents, such as Module Summary, and then have the contents be subsections of Module Contents (as it they are in the non-summary case).
For example, in the above example the new section header structure would be as follows:
Currently, if you include the option
show-module-summary
, then for themes with contents sidebars (such asjupyter-book
), then the lack of a new header before the full module contents docs (i.e. after the last module summary section) means that the page's hierarchy is mis-represented.For example, take the following module, containing a class, attribute and function:
Here we can see the right-hand sidebar displays the contents as one would expect, with each docs entry being a new section in the contents.
However, if we turn on module summaries, we get the following:
Here we can see that the docs entries are displayed as being contents within the last of the module summary sections (in this case
Attributes
, rather than being listed either as at the same hierarchy as the summary sections, or within a new section, thereby indicating they're not withinAttributes
.I'm not sure what the preferred fix for this would be, but probably the most consistent thing would be to move the summary sections into a section above
Module Contents
, such asModule Summary
, and then have the contents be subsections ofModule Contents
(as it they are in the non-summary case).For example, in the above example the new section header structure would be as follows: