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

Jeremy Stanley fungi at yuggoth.org
Thu Aug 20 16:01:18 UTC 2020


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
-------------- 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/20200820/d2e7e3a7/attachment.sig>


More information about the Starlingx-discuss mailing list