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/
can you be a little more specific 
i dont see anythign wrong in the compute api ref it rendered as i expect it to be 
> 
> 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.
can you provide an example fo what the change looks like with or without the setting applied

i dont think there is anything that we shoudl change for novas api ref.
> * Are other openstack projects/APIs impacted by this?
> 
> 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