[docs][all] Important changes in recent openstackdocstheme updates
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 .
* Both reno (since version 3.1.0) and openstackdocsstheme are now
declared parallel safe, the CI jobs automatically build releasenotes
in parallel . 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 .
* small bug fix (if you set auto_name = False in doc/source/conf.py,
this hit so far 5 repos).
Everything is documented in the documentation of openstackdocstheme .
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
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