[Starlingx-discuss] Fwd: [docs][all] Important changes in recent openstackdocstheme updates

Camp, MaryX maryx.camp at intel.com
Thu Jun 4 19:49:37 UTC 2020


Thanks Andreas! I have no experience with theme file updates, your help with the StarlingX docs is much appreciated.

thanks again,
Mary Camp
PTIGlobal Technical Writer | maryx.camp at intel.com

-----Original Message-----
From: Andreas Jaeger <aj at suse.com> 
Sent: Thursday, June 4, 2020 11:55 AM
To: starlingx-discuss at lists.starlingx.io
Subject: [Starlingx-discuss] Fwd: [docs][all] Important changes in recent openstackdocstheme updates

I pushed changes for all starlingx repos that use openstackdocstheme to update to newer version, see the attached email for a longer explanation that I send to the openstack list.

Full set of changes is:

https://review.opendev.org/#/q/topic:reno-openstackdocstheme+is:open+projects:starlingx

If there are any questions, please reach out to me - otherwise, happy reviewing ;)

Andreas

-------- Forwarded Message --------
Subject: [docs][all] Important changes in recent openstackdocstheme updates
Date: Wed, 20 May 2020 17:40:07 +0200
From: Andreas Jaeger <aj at suse.com>
Organization: SUSE Software Solutions Germany GmbH, Nuernberg; GF: Felix Imendörffer; HRB 247165 (AG München)
To: openstack-discuss at lists.openstack.org
<openstack-discuss at lists.openstack.org>
CC: Stephen Finucane <stephenfin at redhat.com>

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
fixes:

* 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 topic:reno-openstackdocstheme.

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

[1]
http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014902.html
[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

_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss at lists.starlingx.io
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss


More information about the Starlingx-discuss mailing list