On 2021-11-04 11:15:13 -0400 (-0400), Ashley Rodriguez wrote:
Recently I've noticed that the h1 text on the manila API ref no longer shows up in the main text body, though it is still listed in the navigation bar on the left hand side. [...]
Can you provide specific URLs? It's a little hard to be sure I understand what you're describing. For example, if you're talking about https://docs.openstack.org/api-ref/shared-file-system/ then when I pull it up in my browser I see "Shared File Systems API" at the top of the main text column. That is H1 level text. I think you may be saying that when there's more than one H1 element in the page, all subsequent H1 elements are hidden? For example, I notice that "API Versions" is the second H1 element, and while it appears in the navigation list in the left column, it does not show up inline in the main text column. This is because OpenStackDocsTheme intentionally hides H1 in the Sphinx output so that it can present a custom styled version of it at the top of the text. This works just fine when there is one and only one top-level (H1) heading element, but breaks down if a document contains more than one.
What I'd like to see in the manila API guide is each resource shown as h1 both in the main body and in the navigation bar, along with each corresponding method. If I were to change the resource titles to h2 I would be able to see the title itself but lose the methods in the nav bar, and yet keeping them as h1 means the side bar works but the main text is missing titles. [...]
Whether they're H1 or H2 level seems more like an implementation detail. What you actually seem to want is just for the document section titles *and* the methods within them to both appear at different levels in the navigation column, right? That seems like something we should be able to solve in the sidebar here: https://opendev.org/openstack/openstackdocstheme/src/branch/master/openstack... You might want to play with setting theme_sidebar_mode to "toc" since it looks like "toctree" implicitly limits the maxdepth to 2 heading levels (H1 and H2 essentially). -- Jeremy Stanley