Open Stack

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/openstackdocstheme/theme/openstackdocs/sidebartoc.html

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20211104/4c66edfc/attachment.sig>