Open Stack

That patch landed; now I proposed
https://review.opendev.org/c/openstack/releases/+/875789 to get it into a
release so we can regenerate our api-refs with the updated docs theme.

-
Jay Faulkner
Ironic PTL
TC Member

On Thu, Feb 23, 2023 at 11:18 AM Stephen Finucane <stephenfin 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/
> >
> > 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.openstack.org/pipermail/openstack-discuss/attachments/20230228/a9492dc1/attachment.htm>