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

Camp, MaryX maryx.camp at intel.com
Thu Sep 3 17:14:33 UTC 2020


Hi Jeremy,
Heads-up that I'm replying to your 2 most recent messages in this 1 email. Hoping that the text makes sense. 

http://lists.starlingx.io/pipermail/starlingx-discuss/2020-August/009530.html 
[...]
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.
[...]

[MaryC ]  In the STX docs meeting yesterday, we discussed your suggestion about forking the theme into the STX docs repo. The team agrees that this is the right time to implement it. Your guidance/help with this process is really appreciated. 

http://lists.starlingx.io/pipermail/starlingx-discuss/2020-September/009543.html 
[...]
In drafting https://review.opendev.org/749369 to implement this alternative matching, it has dawned on me that I'm not entirely clear from the above what your expectations are when publishing. In short, are you publishing from a branch or from a tag? If the former, then the r/stx.4.0 branch's documentation would presumably be published under R4.0 not R4.01. Was that a typo, or is there some missing bit of detail to determine the publication directory from the branch?
[...]

[MaryC ]  
We want to publish from a branch (not tags) and use the branch naming convention. "R4.01" was a typo in my original email.
Corrected text:  Our planned URL structures are: https://docs.starlingx.io/R4.0 (current release) and https://docs.starlingx.io/latest for the master branch.

Please let me know about next steps and recommended actions. 

As an aside, since you mentioned these threads will live on in the ML archives forever, I'm wondering what the etiquette is for modifying the message subject line to be more relevant/useful? 
Maybe adding a descriptor to the end of the subject, like [theme]? 

Thanks again,
Mary C.




More information about the Starlingx-discuss mailing list