<div dir="ltr"><div>That patch landed; now I proposed <a href="https://review.opendev.org/c/openstack/releases/+/875789">https://review.opendev.org/c/openstack/releases/+/875789</a> to get it into a release so we can regenerate our api-refs with the updated docs theme.</div><div><br></div><div>-</div><div>Jay Faulkner</div><div>Ironic PTL</div><div>TC Member<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Feb 23, 2023 at 11:18 AM Stephen Finucane <<a href="mailto:stephenfin@redhat.com">stephenfin@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Thu, 2023-02-23 at 09:54 -0800, Jay Faulkner wrote:<br>
> Hi all,<br>
> <br>
> While investigating some rendering issues with the Ironic api-ref -- headings<br>
> not being shown. We discovered a strange configuration in openstackdocstheme.<br>
> We're not really certain how it's broken, but there is a visual problem that<br>
> needs to be fixed either in the theme or in Ironic's (and others') content.<br>
> <br>
> If you look at <a href="https://docs.openstack.org/api-ref/baremetal/" rel="noreferrer" target="_blank">https://docs.openstack.org/api-ref/baremetal/</a> -- you'll notice<br>
> there are no primary headers. This is because they are in a rst construct<br>
> rendered as an h1, which the CSS in the openstackdocstheme renders to<br>
> display:none:<br>
> <a href="https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/css/combined.css#L929" rel="noreferrer" target="_blank">https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/css/combined.css#L929</a><br>
> <br>
> We also noticed this same rendering issue appears to exist in compute API:<br>
> <a href="https://docs.openstack.org/api-ref/compute/" rel="noreferrer" target="_blank">https://docs.openstack.org/api-ref/compute/</a><br>
> <br>
> But not for Neutron: <a href="https://docs.openstack.org/api-ref/network/v2/index.html" rel="noreferrer" target="_blank">https://docs.openstack.org/api-ref/network/v2/index.html</a>.<br>
> It appears that neutron has added an additional layer of headers which are<br>
> rendering<br>
> (<a href="https://raw.githubusercontent.com/openstack/neutron-lib/master/api-ref/source" rel="noreferrer" target="_blank">https://raw.githubusercontent.com/openstack/neutron-lib/master/api-ref/source</a><br>
> /v2/address-groups.inc) in addition to the headers that are not rendering.<br>
> <br>
> This behavior has been in the openstackdocstheme for years, it was introduced<br>
> in<br>
> <a href="https://github.com/openstack/openstackdocstheme/commit/f81f3344076a09482545534e014318d7e961f825" rel="noreferrer" target="_blank">https://github.com/openstack/openstackdocstheme/commit/f81f3344076a09482545534e014318d7e961f825</a><br>
>   back in 2016.<br>
> <br>
> This raises some questions<br>
> * What's the correct fix? Dmitry is exploring options to do a neutron-style<br>
> workaround in our Ironic api-ref to make them render properly for us; but<br>
> given it's (effectively) broken for Nova as well is an interesting data point<br>
> that might indicate a fix in the theme is needed.<br>
> * Are other openstack projects/APIs impacted by this?<br>
<br>
<br>
I was originally going to blame an overabundance of h1 elements, but nothing in<br>
either HTML or Sphinx prevents multiple h1 elements. The following fix seems to<br>
fix the issue locally for me.<br>
<br>
<a href="https://review.opendev.org/c/openstack/openstackdocstheme/+/874957" rel="noreferrer" target="_blank">https://review.opendev.org/c/openstack/openstackdocstheme/+/874957</a><br>
<br>
Stephen<br>
<br>
> I'm not a documentation or front end html/css expert, so I'm hoping folks with<br>
> more historical context and front end knowledge can respond here and help us<br>
> determine which way to go. In lieu of further input, Ironic will fix our api-<br>
> ref in the same method that Neutron has appeared to be taking and I suggest<br>
> Nova do the same.<br>
> <br>
> Thanks,<br>
> Jay Faulkner<br>
> Ironic PTL<br>
> TC Member<br>
<br>
</blockquote></div>