[Starlingx-discuss] Incorrect "StaringX Documentation" menu

Jeremy Stanley fungi at yuggoth.org
Thu May 25 21:37:16 UTC 2023

On 2023-05-25 17:19:24 -0000 (-0000), ronald.stone at windriver.com wrote:
> The dark blue header on the TOC at the left of each page of
> StarlingX documentation (docs.starlingx.io) has a drop down menu
> titled "StarlingX Documentation", with a triangular 'down' arrow
> to its right. This menu has only two static entries, "Install
> Guides" and "API Guides". The Install Guides entry points to the
> root of the doc set, not the Install Guide. Neither entry updates
> correctly when switching version, e.g. to release 7. 
> We don't see any value in this menu given that complete
> information is available in the TOC and would like to replace it
> with a static header. I do not see any definition for it in
> conf.py.
> How can we change this behavior?

Note that the service-discuss at lists.opendev.org mailing list's scope
is around the services run within the OpenDev Collaboratory, so it's
not that great of a place for projects to discuss changes to their
source code and documentation. Ideally these are the sorts of topics
the StarlingX community will discuss with its membership and develop
its own internal expertise in. The most I can do is some keyword
searches and trying to interpret the results of what I find, and
make connections with other interested parties who may be able to
help. As such, I'm redirecting replies to the starlingx-discuss
mailing list which is better suited for this discussion (I'm
subscribed there too, and do my best to reply to posts where I can
be of help).

Starting with a search for "Install Guides" in the default branches
of Git repositories hosted in OpenDev[*], I see that the string
appears within StarlingX's customization subtree[**] in the
OpenStackDocsTheme project. What little I know about HTML suggests
that removing the content in that file (making it a completely empty
file) will hopefully have the intended effect.

Further searching for references to that sidebartoc_menu.html file
indicates it's unconditionally included in the inherited
OpenStackDocsTheme sidebartoc.html[***] so probably can't be safely
removed without forking that file as well. Note that there is
nothing stopping the StarlingX community from dropping the use of
the OpenStackDocsTheme Sphinx extension and replacing it with a
completely custom theme of their own, which would provide a lot more
direct control over these sorts of details.

Hopefully that helps? If not, lets talk through specifics on the
StarlingX mailing list so that we can build a better understanding
of this among members of the project's community.

[*] https://opendev.org/explore/code?q=Install+Guides
[**] https://opendev.org/openstack/openstackdocstheme/src/commit/88b610f/openstackdocstheme/theme/starlingxdocs/sidebartoc_menu.html
[***] https://opendev.org/openstack/openstackdocstheme/src/commit/b301ee7/openstackdocstheme/theme/openstackdocs/sidebartoc.html#L8
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <https://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20230525/456cb7c3/attachment.sig>

More information about the Starlingx-discuss mailing list