[docs] Double headings on every page

Ashley Rodriguez ashrodri at redhat.com
Thu Nov 4 15:15:13 UTC 2021


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 at 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?
>
> [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 at 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 at 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:
>>>
>>>
>>> https://opendev.org/openstack/charm-deployment-guide/src/branch/master/deploy-guide/source/app-nova-cells.rst
>>>
>>> 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
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20211104/7cefc1b7/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image.png
Type: image/png
Size: 7527 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20211104/7cefc1b7/attachment.png>


More information about the openstack-discuss mailing list