Open Stack

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

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
>
>