[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-08-19
Hello all, Here are this week's docs team meeting minutes (short form). Details in [2]. Join us if you have interest in StarlingX docs! We meet on Wednesdays 12:30 PST.
[1] Call logistics: https://wiki.openstack.org/wiki/Starlingx/Meetings [2] Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation
thanks, Mary Camp ========== 2020-08-19
All -- reviews merged since last meeting: 1 All -- bug status -- 10 total Reviews in progress: Several reviews related to Rook are ready to review per discuss list message: http://lists.starlingx.io/pipermail/starlingx-discuss/2020-August/009452.htm... Editorial updates on simplex & duplex Ceph Cluster Migration guide https://review.opendev.org/#/c/745623/ Deployment guide for rook aio-duplex deployment https://review.opendev.org/#/c/742573/ Deployment guide for rook aio-sx deployment https://review.opendev.org/#/c/742102/ Deployment guide for rook deployment https://review.opendev.org/#/c/724623/ Add backup and restore guide for rook provisioned system https://review.opendev.org/#/c/739900/
All -- Opens Can the test team be looped in to test some of our complicated procedures (ie install/deployment guides)? Greg and Mary will attend the Test meeting and ask them about it. [Next meeting 1Sept @ 8 am PDT]
How are doc inputs received from the development team / community? launchpad, email on discuss, storyboard item, and email. Preference is to submit a review following contributor guidelines or launchpad.
Upstreaming WR docs Team has been waiting for the script to do the dita -> rst conversion, it will be available for their testing starting tomorrow. They will select first ~6 reviews tomorrow. Planning to select a representative group of docs with tables, diagrams to see how the conversion scripts play out. We discussed which topics would be best to start with. Topics not already in the STX guides will test the conversion without getting into the reorganization effort. Possibly security, system config and mgmt, node config & mgmt. Recommend making a local clone of the repository and build the docs on your own machine. Then submit the gerrit reviews to see how that process works. Use DONT MERGE or WIP in commit message to identify the reviews.
Version/tagging of STX docs Ildiko talked to Doug who was involved when STX docs were first set up. It's been a while... he suggested that we start by deciding what the docs URL should look like, for example, what will be the "release" identifier (name, number, something else?). That will help us decide how to handle the repository. Probably won't need all the structure that OpenStack manuals uses (because they pull from so many different projects). Dig into some of the OS templates, figure out where the release info gets pulled into the scripts. Use the stable branches and dig into how the OpenStack docs are working. Jimmy and Jeremy may be helpful with the URL decision also. Next steps: URL structure - decide it. Look at build jobs for the OS jobs.
On 2020-08-20 01:34:37 +0000 (+0000), Camp, MaryX wrote: [...]
Version/tagging of STX docs Ildiko talked to Doug who was involved when STX docs were first set up. It's been a while... he suggested that we start by deciding what the docs URL should look like, for example, what will be the "release" identifier (name, number, something else?). That will help us decide how to handle the repository. Probably won't need all the structure that OpenStack manuals uses (because they pull from so many different projects). Dig into some of the OS templates, figure out where the release info gets pulled into the scripts. Use the stable branches and dig into how the OpenStack docs are working.
Jimmy and Jeremy may be helpful with the URL decision also.
Next steps: URL structure - decide it. Look at build jobs for the OS jobs.
[...]
I looked closer at these some last week. In OpenStack this is done two different ways...
The central repository for the main https://docs.openstack.org/ site is "branchless" (from a Git perspective) and maintains parallel directory trees for the various releases:
https://opendev.org/openstack/openstack-manuals/src/branch/master/www
The project-specific documentation such as https://docs.openstack.org/nova/ussuri/admin/ is embedded within the project repositories and so it branches along with them:
https://opendev.org/openstack/nova/src/branch/stable/ussuri/doc/source/admin
I would say this is really the first question to answer when it comes to designing your publication pipeline. I gather you plan to keep a single, central documentation repository for now; do you want a repository branch for each version of the documentation or to keep the various versions in different directories within a single branch? The answer to this will determine how your publication jobs need to work (whether they build all versions each time they're updated and then redeploy the entire site, or build only the version which is being modified and then deploy just that part of the site). We've basically solved this both ways, so can fairly easily support either option.
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.
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. 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
Appreciate your guidance for next steps to making this work. thanks, Mary Camp PTIGlobal Technical Writer | maryx.camp@intel.com
-----Original Message----- From: Jeremy Stanley fungi@yuggoth.org Sent: Thursday, August 20, 2020 12:01 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] [docs] [meeting] Docs team notes 2020-08-19
On 2020-08-20 01:34:37 +0000 (+0000), Camp, MaryX wrote: [...]
Version/tagging of STX docs Ildiko talked to Doug who was involved when STX docs were first set up. It's been a while... he suggested that we start by deciding what the docs URL should look like, for example, what will be the "release" identifier (name, number, something else?). That will help us decide how to handle the repository. Probably won't need all the structure that OpenStack manuals uses (because they pull from so many different projects). Dig into some of the OS templates, figure out where the release info gets pulled into the scripts. Use the stable branches and dig into how the OpenStack docs are working.
Jimmy and Jeremy may be helpful with the URL decision also.
Next steps: URL structure - decide it. Look at build jobs for the OS jobs.
[...]
I looked closer at these some last week. In OpenStack this is done two different ways...
The central repository for the main https://docs.openstack.org/ site is "branchless" (from a Git perspective) and maintains parallel directory trees for the various releases:
https://opendev.org/openstack/openstack-manuals/src/branch/master/www
The project-specific documentation such as https://docs.openstack.org/nova/ussuri/admin/ is embedded within the project repositories and so it branches along with them:
https://opendev.org/openstack/nova/src/branch/stable/ussuri/doc/source/admin
I would say this is really the first question to answer when it comes to designing your publication pipeline. I gather you plan to keep a single, central documentation repository for now; do you want a repository branch for each version of the documentation or to keep the various versions in different directories within a single branch? The answer to this will determine how your publication jobs need to work (whether they build all versions each time they're updated and then redeploy the entire site, or build only the version which is being modified and then deploy just that part of the site). We've basically solved this both ways, so can fairly easily support either option. -- 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/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.
On 2020-08-28 14:57:36 +0000 (+0000), Camp, MaryX wrote: [...]
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.
[...]
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?
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.htm... [...] 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. [...]
[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.... [...] 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.
On 2020-09-03 17:14:33 +0000 (+0000), Camp, MaryX wrote: [...]
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.
[...]
My pleasure. Probably the place to start is copying the files from the openstackdocstheme subdirectory of the openstack/openstackdocstheme repository into the appropriate locations for the doc/source tree of the starlingx/docs repository. The up side to this move is that it will be tested completely with draft renderings we can check over before it's ever approved and deployed. I'll abandon https://review.opendev.org/749369 but we'll want to make sure to incorporate a similar change into the new extension script in starlingx/docs.
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.
Great, thanks confirming! That will make all this a lot simpler than trying to derive version numbers from something other than the branch name.
Please let me know about next steps and recommended actions.
I outlined the general idea above, but the specifics will probably take as much effort to write up as it would to just push an initial attempt myself. I can have something up for review in the next day or so with copies of the files in the places I expect they should go, but I'm also no expert when it comes to Sphinx so am just as happy for someone else to give it a shot instead, if there are any volunteers for that (in which case I'll gladly help review and debug the result).
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]?
The conventional way, which I've done just now in this reply, is to replace the subject but follow it with all or some of the old subject in parentheses with a preceding "was:" to indicate this is a subthread of the original discussion topic. The OpenStack community documents this in their wiki article on Mailing List Etiquette, though it's really just a long-standing entrenched tradition on most of the technical mailing lists to which I've ever subscribed:
https://wiki.openstack.org/wiki/MailingListEtiquette#Changing_Subject
On 2020-09-03 17:14:33 +0000 (+0000), Camp, MaryX wrote: [...]
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.
[...]
Oh, one other upshot I likely missed mentioning (since it didn't dawn on me until just now), putting the theme in a branched repository and building documentation from each branch will require that the theme implementation gets backported to the existing branches, and any changes you make to theming over time would also need to be backported accordingly to maintain consistency. It's probably not a big deal since those files are unlikely to ever diverge, only become outdated, so as long as you backport each change to the theme and extensions it should be trivial to maintain. Still, it *is* one more thing to remember when proposing, reviewing, and approving changes for those files.
participants (2)
-
Camp, MaryX
-
Jeremy Stanley