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/walla...

Source file is here:

https://opendev.org/openstack/charm-deployment-guide/src/branch/master/deplo...

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

[1] https://docs.openstack.org/nova/latest/configuration/extra-specs.html

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: image.png]

We patched [1] our project as a workaround.

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

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/walla...

Source file is here:

https://opendev.org/openstack/charm-deployment-guide/src/branch/master/deplo...

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

[1] https://docs.openstack.org/nova/latest/configuration/extra-specs.html

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).