[all][docs] Inconsistencies in api-ref rendering - impacting compute and baremetal api-ref, maybe others
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/openstackdocsthe...
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/sourc...) 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/f81f3344076a094825455... 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'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
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/openstackdocsthe...
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/sourc...) 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/f81f3344076a094825455... 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
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@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/openstackdocsthe...
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/sourc...) 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/f81f3344076a094825455... 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
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@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/openstackdocsthe...
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/sourc...) 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/f81f3344076a094825455... 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
I noticed something was off with the Designate api-ref as well, but didn't realize what it was since I didn't create it. Good catch.
So, yes, Designate is also impacted and I think we should fix the theme.
Michael
On Thu, Feb 23, 2023 at 10:00 AM Jay Faulkner jay@gr-oss.io 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/openstackdocsthe...
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/sourc...) 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/f81f3344076a094825455... 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'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
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/openstackdocsthe...
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/sourc... /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/f81f3344076a094825455... 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
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@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/openstackdocsthe...
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/sourc...
/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/f81f3344076a094825455...
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
participants (4)
-
Jay Faulkner
-
Michael Johnson
-
Sean Mooney
-
Stephen Finucane