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

[Camp, MaryX]

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 at intel.com

-----Original Message-----
From: Jeremy Stanley <fungi at yuggoth.org> 
Sent: Thursday, August 20, 2020 12:01 PM
To: starlingx-discuss at 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