[docs][all] Important changes in recent openstackdocstheme updates

Andreas Jaeger aj at suse.com
Wed May 20 15:40:07 UTC 2020

A couple of changes recently merged into openstackdocstheme to fix
problems reported. These had some surprises in it and we'd like to
inform you about the changes:

* Config options are now prefixed with openstackdocs_, the old names
  will be removed in a future release

* The 'project' config option is now only respected (and displayed in
  the left menu) if 'openstackdocs_auto_name = False' is set. By
  default, the theme uses the package name (from setup.cfg)

* The HTML files show the version number by default (with exception of
  releasenotes and api docs) calculated from git. If you want to use
  your own version number or disable it, set
  'openstackdocs_auto_version = False' and manually configure the
  'version' and 'release' options.

* Previously, the theme always used 'pygments_style = "native"' and
  overrode the setting of 'sphinx' that many repos have. Now the setting
  is respected. For a few repos this lead to unreadable code snippets.
  If you see this or want to go back to the previous theme, configure
  'pygments_style = "native"'.

* Many projects have written PDF documents. openstackdocstheme can now
  optionally link to them. Set 'openstackdocs_pdf_link' to True to show
  the icon with path. Note that the PDF file is placed on
  docs.openstack.org in the top of the html files while in check/gate
  it's in a separate PDF folder. Thus, the site preview will show in
  check/gate a broken link - but it works fine, check [2].

* Both reno (since version 3.1.0) and openstackdocsstheme are now
  declared parallel safe, the CI jobs automatically build releasenotes
  in parallel [1]. You can modify your local tox job to do this by
  adding the '-j auto' parameter to your 'sphinx-build' invocation.

We're releasing openstackdocstheme version 2.2.1 soon with two further

* PDF documents will now show the version number like html document, no
  need to configure versions in conf.py for this anymore [3].
* small bug fix (if you set auto_name = False in doc/source/conf.py,
  this hit so far 5 repos)[4].

Everything is documented in the documentation of openstackdocstheme  [2].

If there are any questions, best ask in #openstack-oslo.

Andreas has started pushing changes to update projects with

Hope that's all for Victoria on the openstackdocstheme,
Stephen and Andreas

[2] https://docs.openstack.org/openstackdocstheme/
[3] https://review.opendev.org/729554
[4] https://review.opendev.org/729031
 Andreas Jaeger aj at suse.com Twitter: jaegerandi
  SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, D 90409 Nürnberg
   (HRB 36809, AG Nürnberg) GF: Felix Imendörffer
    GPG fingerprint = EF18 1673 38C4 A372 86B1  E699 5294 24A3 FF91 2ACB

More information about the openstack-discuss mailing list