[OpenStack-docs] openstackdocstheme and Mitaka release?

Andreas Jaeger aj at suse.com
Tue Mar 15 19:47:00 UTC 2016

Currently our guides using openstackdocstheme (and that includes also
documents like Compute API in the nova repository) hardcode the release
name and links to releases in them.

See the attached screenshot for an example or look directly at one of
the guides like http://docs.openstack.org/admin-guide-cloud/ .

This already confused some folks since we always build with latest theme
and thus the kilo guide now will have Liberty in the theme. Also, we
have guides that are version independent - we call them also continously
released - like User Guides. These cover the current "supported"
releases but they have only "Liberty" written on them.

With each OpenStack release we face the challenge to update the
openstackdocstheme at the right time. We don't want to do it too early -
so not have yet Mitaka out - but also not to late - we'd love to be
ready when Mitaka is out. This puts stress on OpenStack and
documentation release teams to release this timely - against the normal
policies setup for releases.

I chatted earlier today with Doug Hellmann and Dims and we discussed
some options including the following:

1) Leave status quo.
2) Enhance openstackdocstheme to have an option that names the release.
This means we need to add to each of the 10+ repos currently using it
this option. Advantages are that we could even have different links
there - for Liberty guides, links to Liberty, for Mitaka ones, links to
3) Add the next release links far earlier (now). This will remove
pressure everywhere but forces us to publish a docs.openstack.org/mitaka
page as well.
4) Remove the version completely, instead point to docs.openstack.org
top level page. In that case, we should also remove the list of releases
from the navigation bar.
5) Any other options we didn't think about?

I'm in favor of option 4 since that avoids confusion and avoids last
minute changes.

What are your suggestions?

Btw. volunteers to implement a solution are also welcome,

 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot from 2016-03-15 20-17-07.png
Type: image/png
Size: 28677 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160315/f4e3aeed/attachment-0001.png>

More information about the OpenStack-docs mailing list