Open Stack

On Thu, 2023-02-23 at 10:49 -0800, Michael Johnson wrote:
> Sean, I see it in the compute api-ref.
> 
> If you click here: https://docs.openstack.org/api-ref/compute/#servers-servers
> You will see that the:
> 
> ===================
>  Servers (servers)
> ===================
> 
> from the RST is not rendered in the body, only the left nav.
> 
> https://github.com/openstack/nova/blame/master/api-ref/source/servers.inc#L5

oh ok i see. ya we probaly shoudl fix that.
> 
> Michael
> 
> On Thu, Feb 23, 2023 at 10:15 AM Sean Mooney <smooney at redhat.com> wrote:
> > 
> > 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
> > 
> > 
>