[all] [tc] [docs] [release] [ptls] Docs as SIG: Ownership of docs.openstack.org

Doug Hellmann doug at doughellmann.com
Mon Aug 19 18:16:13 UTC 2019



> On Aug 19, 2019, at 1:56 PM, Jeremy Stanley <fungi at yuggoth.org> wrote:
> 
> On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote:
> [...]
>> there seems to be a big difference between owning the task of
>> configuring the site for the next release (which totally makes
>> sense as a release team task) and owning the entire
>> docs.openstack.org site.
> 
> That's why I also requested clarification in my earlier message on
> this thread. The vast majority of the content hosted under
> https://docs.openstack.org/ is maintained in a distributed fashion
> by the various teams writing documentation in their respective
> projects. The hosting (configuration apart from .htaccess files,
> storage, DNS, and so on) is handled by Infra/OpenDev folks. If it's
> *just* the stuff inside the "www" tree in the openstack-manuals repo
> then that's not a lot, but it's also possible what the release team
> actually needs to touch in there could be successfully scaled back
> even more (with the caveat that I haven't looked through it in
> detail).
> -- 
> Jeremy Stanley


The suggestion is for the release team to take over the site generator
for docs.openstack.org (the stuff under “www” in the current
openstack-manuals git repository) and for the SIG to own anything
that looks remotely like “content”. There isn’t much of that left anyway,
now that most of it is in the project repositories.

Most of what is under www is series-specific templates and data files
that tell the site generator how to insert links to parts of the
project documentation in the right places (the “install guides” page links
to /foo/$series/install/ for example). They’re very simple, very dumb, 
templates, driven with a little custom script that wraps jinja2, 
feeding the right data to the right templates based on series name.
There is pretty good documentation for how to use it in the
tools [1] and release [2] sections of the docs contributor guide.

The current site-generator definitely could be simpler, especially
if it only linked to the master docs and *those* linked to the older
versions of themselves (so /nova/latest/ had a link that pointed to
/nova/ocata/ somewhere). That would take some work, though.

The simplest thing we could do is just make the release team committers
on openstack-manuals, leave everything else as it is, and exercise
trust between the two groups. If we absolutely want to separate the builds,
then we could make a new repo with just the template-driven pages under “www”,
but that’s going to involve changing/creating several publishing jobs.

Doug

[1] https://docs.openstack.org/doc-contrib-guide/doc-tools.html
[2] https://docs.openstack.org/doc-contrib-guide/release.html




More information about the openstack-discuss mailing list