[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+project... 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@suse.com> Organization: SUSE Software Solutions Germany GmbH, Nuernberg; GF: Felix Imendörffer; HRB 247165 (AG München) To: openstack-discuss@lists.openstack.org <openstack-discuss@lists.openstack.org> CC: Stephen Finucane <stephenfin@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@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
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@intel.com -----Original Message----- From: Andreas Jaeger <aj@suse.com> Sent: Thursday, June 4, 2020 11:55 AM To: starlingx-discuss@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+project... 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@suse.com> Organization: SUSE Software Solutions Germany GmbH, Nuernberg; GF: Felix Imendörffer; HRB 247165 (AG München) To: openstack-discuss@lists.openstack.org <openstack-discuss@lists.openstack.org> CC: Stephen Finucane <stephenfin@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@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@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
participants (2)
-
Andreas Jaeger
-
Camp, MaryX