Changes

3.5.0-3

New Features

• Add an optional project-scoped search bar to the sidebar. Updated OpenStack/StarlingX wide search placeholder to “Global Search” for clarity.

Upgrade Notes

• Support for Python 3.8 and 3.9 has been removed. Now the minimum Python version supported is 3.10.

2.2.1

New Features

• PDF files will now automatically display the version number like HTML files do already if openstackdocs_auto_version is True (default value).

2.2.0

New Features

• The theme can now include links on each page to a PDF file. Set the new config option openstackdocs_pdf_link to enable it and configure the file name if needed with the new config option openstackdocs_pdf_filename.

2.1.2

Bug Fixes

• latex_engine is always set to xelatex, there’s no good solution to check whether it is overriden. This restores the behavior before version 2.1.0.

2.1.0

New Features

• A new config option, openstackdocs_auto_name, has been added. This can be used to disable auto-configuration of the project name through inspection of package metadata.

• A new config option, openstackdocs_auto_version, has been added. This can be used to disable auto-versioning of documentation for things like release notes or API references.

Upgrade Notes

• The openstackdocs_auto_version option must be configured to disable auto-versioning of documentation. Previously, the extension would check for an empty string ('') and, if present, use this to indicate that the document should be unversioned. However, this only worked if building documentation using the build_sphinx distutils extension.

• All configuration options are now prefixed with openstackdocs_. Support for the previous configuration option names are considered deprecated and will be removed in a future release.

  Affected options

  New Name	Deprecated Name
  openstackdocs_repo_name	repository_name
  openstackdocs_use_storyboard	use_storyboard
  openstackdocs_bug_project	bug_project
  openstackdocs_bug_tag	bug_tag
  openstackdocs_project	openstack_project

Bug Fixes

• The latex_engine and latex_elements options, which were previously always overridden by the extension, will now be merged with user configuration. If latex_engine is configured by the user, this will be used in-place of the default. If latex_elements, a dictionary, is configured, the values provided by the user will be merged with the defaults with user-provided defaults preferred.

2.0.0

Upgrade Notes

• Python 2.7 support has been dropped. The minimum version of Python now supported by openstackdocstheme is Python 3.6.

1.31.0

Other Notes

• As a result of the CSS coverage improving, a large number of the unused CSS rules have been removed.

1.30.0

Bug Fixes

• Allow to override build date of generated files with SOURCE_DATE_EPOCH in order to make build results of packages fully reproducible especially when building from tarballs without a .git directory.

1.29.3

Other Notes

• The rendered git URL now uses https://opendev.org as git repository URLs.

1.28.0

New Features

• Add tools for building translated documents. The file docstheme-build-translated.sh will look for translations and build translated documents for all languages that exist. Invoke docstheme-build-translated.sh from tox.ini instead of running sphinx-build directly. The following environment variables control the script: SKIP_SPHINX_WARNINGS to not treat warnings from sphinx-build as an error. SPHINX_WARNINGS_TRANS will turn on warnings by sphinx-build as an error on translation (use with caution).

  Example for tox.ini:

  [testenv:docs]
  deps = -r{toxinidir}/doc/requirements.txt
  setenv =
      SKIP_SPHINX_WARNINGS=1
  commands=
      docstheme-build-translated.sh
  

• The “last-updated” page context for each page is set based on the git history for the source document for the page. If there is no source document checked into git, the current time is used.

1.27.0

Bug Fixes

• Fix API breakages in 1.26.0: Readd get_openstack_logo_path, add default parameter to get_pdf_theme_path.

1.26.0

New Features

• Add support for including additional themes in the package, starting with starlingxdocs. The initial implementation sets up the new theme to inherit from openstackdocs and updates some of the openstackdocs bits that are hard coded in the Python.

  For example:

  html_theme = 'starlingxdocs'
  

1.24.0

Bug Fixes

• If you use storyboard via use_storyboard, now only repository_name is used and not bug_project anymore to construct the URL for storyboard. The generated URL has been fixed as well.

1.23.1

New Features

• A badge pointing out the support status of a document is shown now for repositories that have stable/ branches. The badge is not displayed for api-ref, api-guide and releasenotes documents. It can be disabled with the display_badge html theme option.

Bug Fixes

• Storyboard shows now instead of numbers the name of the project group. Allow setting this as string. In this case the variable use_storyboard needs to be set.

1.20.0

New Features

• The following configuration variables, normally defined in conf.py, can now be configured automatically.

  • project

  • version

  • release

  • html_last_updated_fmt

  • latex_engine

  • latex_elements

  It is not necessary to retain any configuration in conf.py and, in most cases, such configuration will be ignored. The sole exceptions to this rule are version and release which, if set to '' will not be overridden. This allows for unversioned documentation.

1.18.0

Bug Fixes

• The double backticks (``) markup caused text to be displayed in red with a pinkish background colour. The text is now displayed in black and bold.

1.17.0

Prelude

Adds scoped search so that readers can search within project documentation only.

New Features

• Adds ability to use the Sphinx search implementation only for the content for the project, such as nova or keystone. The default settings set the search scope to within the built version and only for .html files.

• Readers access the search functionality through a link to Search from the top-most landing page for the project documentation.

1.13.0

Bug Fixes

• The title “Contents” of the page local TOC is now displayed only when a page has sub-titles.

• The navigation links now correctly strip HTML from titles, allowing for use of markup like literal backticks in titles.

1.12.0

Prelude

Adds ability to show up to the last five versions of the documentation, based on the available git tags for the repository. Use the theme variable, show_other_versions to chose to display the available versions in a dropdown menu.

New Features

• Initial integration of storyboard.openstack.org for report a bug, set bug_project to the number of the project to use it.

• Adds the option to configure the display of a version selector dropdown menu for the most recent five git tags used as release indicators for the repository. By default, in theme.conf, the show_other_versions value is set to False. In conf.py, set the theme variable, html_theme_options to include the parameter, show_other_versions as True. For example:

  html_theme_options = {'show_other_versions': True}
  

• Publishes a version dropdown menu in the “Updated” date row, on both mobile and desktop views, where the version list is imported from git tags on the repository.

Bug Fixes

• If bug_project is not set, the “Report a bug” links are not displayed at all.

1.6.1

New Features

• Adds additional information to the doc bug template used on Launchpad when a reader clicks the doc bug icon to report a bug.

Other Notes

• Implemented intially to guide people to better ways to get end-user support rather than log a doc bug.

1.5.0

Prelude

Adds a theme variable, sidebar_dropdown to configure the display of the new API sidebar dropdown menu.

New Features

• The automatic table of contents that appears in the body of the documentation can be disabled by setting display_toc to False in the html_theme_options option in conf.py.

  For example:

  html_theme_options = {
       "display_toc": False,
  }
  

• Adds the option to configure the display of a sidebar dropdown menu for published API References and Guides. In conf.py, set the theme variable, html_theme_options to include the parameter, sidebar_dropdown as api_ref. For example:

  html_theme_options = {
       "sidebar_dropdown": "api_ref",
    }
  

  The extensions parameter should include the sphinx extension, os_api_ref.

  extensions = [
      'os_api_ref',
  ]
  

• Publishes an API Reference demo which is integrated with the API sidebar dropdown menu.

1.4.0

Prelude

In preparation for releasing updated API reference documentation using this theme, we have a collection of new features and fixes.

New Features

• The ability to customise the bug title for the ‘Report a Bug’ link is now available. To customise the bug title used add the bug_title key with a value to html_context in the Sphinx configuration.

  For example:

  html_context = {"bug_title": 'Documentation bug', ...}
  

• Ensure Javascript and CSS files are pulled in programmatically to enable custom Javascript and CSS files.

• CSS adjustments to inline markup and contents indentation.

• Enable custom bug title link.

• Adds sidebar_mode for table of contents as an option for html_theme_options in conf.py.

• The sidebar Table of Contents can now be set to the full toc directive, or remain as the toctree directive.

  This can be set by setting "sidebar_mode" to "toc" in the html_theme_options option in conf.py.

  For example:

  html_theme_options = {
       "sidebar_mode": "toc",
    }
  

Bug Fixes

• Use HTTPS for external dependencies.

• Replace deprecated library function os.popen() with subprocess. (1529836)

• Update contribute link in footer. (1421814)

• Hide duplicate titles and empty tocs in generated content.

1.3.0

Other Notes

• The sidebar is not version dependent anymore, it always links to the main page.

1.2.7

Bug Fixes

• Fix links on sidebar to go to docs.openstack.org instead of non-existing places (Launchpad bug

1.2.6

New Features

• Some teams use openstackdocstheme which have each launchpad project. To report a bug to the appropriate project directly, enable each project to define the bug report project.

• Google Analytics tracking may now be controlled by setting the analytics_tracking_code option, or removed entirely by leaving that option blank.

1.2.5

New Features

• Contents in the sidebar TOC is now a link to a top page of a document which contains a toc of the document. Now readers can easily move back to a full toc of a document.

Bug Fixes

• Add Google Analytics JavaScript tracking snippet code to resolve Launchpad bug

Other Notes

• Use reno for release note management.