On 2020-08-28 14:57:36 +0000 (+0000), Camp, MaryX wrote:
Thanks for the help Jeremy. In the docs meeting this week, the team agreed to follow the 2nd option you mentioned: the project-specific model and we'll branch the docs when the other STX repos branch.
The STX docs repo already has an R4 branch: https://opendev.org/starlingx/docs/src/branch/r/stx.4.0 so that part is done. Our planned URL structures are: https://docs.starlingx.io/R4.01 (current release) and https://docs.starlingx.io/latest for the master branch.
Great, that helps narrow down what we need to consider.
Our goal is for the STX docs website to operate like the Horizon one with a version selection button in the titlerow.html (Nova doesn't have this button). On the STX website, the button is implemented, but only "latest" is available.
Oh, yep, I hadn't even spotted that control. I guess I've been trained to ignore anything rendered in grey.
Horizon examples: https://docs.openstack.org/horizon/latest/ and https://docs.openstack.org/horizon/ussuri/
The Horizon docs are included in the project repo here: https://opendev.org/openstack/horizon/src/branch/master/doc [...]
Thanks, examples are very useful since it's often easier to do a bit of reverse engineering to find out how it got implemented. In this case I see the problem straight away. The Sphinx extension which identifies the version names can be found here: <URL: https://opendev.org/openstack/openstackdocstheme/src/commit/0ef4eb20b4c74c70... > [Forgive the long permalink, it's for posterity since this discussion will live in the ML archive long after the file in Git has changed.] As you can see, that script is, at documentation build time, scraping the project repository's branch list to find any which start with the prefix "stable" (an OpenStack convention) so that it can figure out what "interesting_series" to return in the _get_other_versions() function. That entire extension is, quite frankly, full of OpenStackisms. I can imagine two solutions to this: expand the extension's scope or fork it. I suppose there's also a middle ground where we extract the OpenStackisms from ext.py into a separate replaceable module and then we'd only need to fork that module. I'll see if anybody in the OpenStack Technical Writing SIG has an opinion on whether the scope expansion or refactoring solutions would be acceptable to them, since they're co-maintainers of openstackdocstheme (along with the OpenStack Oslo team). Ultimately, though, if you're considering eventually forking all of openstackdocstheme anyway, this might be the change which pushes that decision over the edge. -- Jeremy Stanley