[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-08-19

[Jeremy Stanley]

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/0ef4eb20b4c74c70b934e6dca48525328c0577dd/openstackdocstheme/ext.py >

[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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20200831/8c1bd0b2/attachment.sig>