Open Stack

On Thu, 2023-02-23 at 09:54 -0800, Jay Faulkner wrote:
> Hi all,
> 
> While investigating some rendering issues with the Ironic api-ref -- headings
> not being shown. We discovered a strange configuration in openstackdocstheme.
> We're not really certain how it's broken, but there is a visual problem that
> needs to be fixed either in the theme or in Ironic's (and others') content.
> 
> If you look at https://docs.openstack.org/api-ref/baremetal/ -- you'll notice
> there are no primary headers. This is because they are in a rst construct
> rendered as an h1, which the CSS in the openstackdocstheme renders to
> display:none:
> https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/css/combined.css#L929
> 
> We also noticed this same rendering issue appears to exist in compute API:
> https://docs.openstack.org/api-ref/compute/
> 
> But not for Neutron: https://docs.openstack.org/api-ref/network/v2/index.html.
> It appears that neutron has added an additional layer of headers which are
> rendering
> (https://raw.githubusercontent.com/openstack/neutron-lib/master/api-ref/source
> /v2/address-groups.inc) in addition to the headers that are not rendering.
> 
> This behavior has been in the openstackdocstheme for years, it was introduced
> in
> https://github.com/openstack/openstackdocstheme/commit/f81f3344076a09482545534e014318d7e961f825
>   back in 2016.
> 
> This raises some questions
> * What's the correct fix? Dmitry is exploring options to do a neutron-style
> workaround in our Ironic api-ref to make them render properly for us; but
> given it's (effectively) broken for Nova as well is an interesting data point
> that might indicate a fix in the theme is needed.
> * Are other openstack projects/APIs impacted by this?


I was originally going to blame an overabundance of h1 elements, but nothing in
either HTML or Sphinx prevents multiple h1 elements. The following fix seems to
fix the issue locally for me.

https://review.opendev.org/c/openstack/openstackdocstheme/+/874957

Stephen

> I'm not a documentation or front end html/css expert, so I'm hoping folks with
> more historical context and front end knowledge can respond here and help us
> determine which way to go. In lieu of further input, Ironic will fix our api-
> ref in the same method that Neutron has appeared to be taking and I suggest
> Nova do the same.
> 
> Thanks,
> Jay Faulkner
> Ironic PTL
> TC Member