Hi! 

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. 
I've noticed a similar issue on the Ironic, Nova, Neutron API guides as well. 
I think the change you mentioned caused this, though I'm not completely sure since not all API guides are affected. 
For example, Swift's API guide still works as expected with visible header 1s identifying the resource, and each method being listed in the nav bar as well.
Cinder's API guide makes use of h2 instead, and thus doesn't have each method listed in the nav bar, though the titles are visible. 
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. 
I don't have much experience with front-end work so I'd really appreciate any guidance you can offer to fix this. 

Thanks,
Ashley

On Tue, Aug 10, 2021 at 8:05 PM Peter Matulis <peter.matulis@canonical.com> wrote:
I'm now seeing this symptom on several projects in the 'latest' release branch. Such as:

https://docs.openstack.org/nova/latest/

My browser exposes the following error:

image.png

We patched [1] our project as a workaround.

Could one of Stephen's commits [2] be involved?

[1]: https://review.opendev.org/c/openstack/charm-deployment-guide/+/803531
[2]: https://opendev.org/openstack/openstackdocstheme/commit/08461c5311aa692088a27eb40a87965fd8515aba

On Thu, Jun 10, 2021 at 3:51 PM Peter Matulis <peter.matulis@canonical.com> wrote:
Hi Stephen. Did you ever get to circle back to this?

On Fri, May 14, 2021 at 7:34 AM Stephen Finucane <stephenfin@redhat.com> wrote:
On Tue, 2021-05-11 at 11:14 -0400, Peter Matulis wrote:
Hi, I'm hitting an oddity in one of my projects where the titles of all pages show up twice.
 
Example:

https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/wallaby/app-nova-cells.html

Source file is here:


Does anyone see what can be causing this? It appears to happen only for the current stable release ('wallaby') and 'latest'.

Thanks,
Peter

I suspect you're bumping into issues introduced by a new version of Sphinx or docutils (new versions of both were released recently).

Comparing the current nova docs [1] to what you have, I see the duplicate <h1> element is present but hidden by the following CSS rule:

.docs-body .section h1 {
    display: none;
}

That works because we have the following HTML in the nova docs:

<div class="section" id="extra-specs">
    <h1>Extra Specs<a class="headerlink" href="#extra-specs" title="Permalink to this headline">¶</a></h1>
    ...
</div>

while the docs you linked are using the HTML5 semantic '<section>' tag:

<section id="nova-cells">
    <h1>Nova Cells<a class="headerlink" href="#nova-cells" title="Permalink to this headline">¶</a></h1>
    ...
</section>

So to fix this, we'll have to update the openstackdocstheme to handle these changes. I can try to take a look at this next week but I really wouldn't mind if someone beat me to it.

Stephen