Skip to content

Change log

Jump to bottom
Ruth Fuchss edited this page Dec 15, 2023 · 25 revisions

For the full change log, see the commits or pull requests. This change log lists big and relevant changes that every user of the starter pack should be aware of and that might require an action.

2023/12/13

The name of the lxd-sphinx-extensions package changed to canonical-sphinx-extensions. This shouldn't impact any existing configurations because redirect mechanisms are in place. However, you should update the package name eventually.

2023/10/17

The gh-jira-sync-bot was recently enabled for all Canonical repositories, which means that all repositories will now automatically sync their GitHub issues to Jira with the default configuration (thus to the documentation practice project). To prevent this, we have removed the gh-jira-sync-bot from the starter pack, and we'll look into alternatives.

2023/10/13

Added a script init.sh and associated instructions to partially automate the initialisation of a documentation repository using the starter pack. Usage of the script is optional; the existing manual instructions for initialising a documentation repository still stand.

2023/10/11

Added a html_title variable to custom_conf.py that can be used to configure or turn off the documentation title that is displayed in the sidebar.

2023/09/26

Added a sequential_nav variable allowing users to control whether the "Next" and "Previous" buttons appear in footer. This can be controlled globally and overridden on a per-page level.

2023/09/26

Moved the Sphinx doctrees out of the build directory and moved the colour definitions to a separate CSS file to reduce the size of the generated documentation. This is mainly relevant when packaging documentation with the product, but it can also reduce loading times for documentation hosted on RTD.

2023/09/20

Added some common terms to the custom wordlist, including Canonical-specific terms.

2023/08/31

Unpinned the Sphinx version again since the issues (mentioned below, 2023/08/21) are now fixed.

2023/08/22

Switched the GitHub documentation checks to use a reusable workflow.

2023/08/21

Pinned the Sphinx version to prevent some current bugs (that will hopefully be resolved soon):

Therefore, we currently pin the Sphinx version to 7.1.2.

2023/08/16

Added a GitHub bot that can be used to sync issues from GitHub to Jira. See (Optional) Synchronise GitHub issues to Jira for instructions on how to set it up.

2023/07/10

Summary of relevant changes for the last month:

  • Moved the content files that were meant to show how to set up Diataxis documentation to a separate repository: https://github.com/canonical/example-product-documentation

    This leaves only the files that cover configuration and styling in the starter pack, which should make it easier to keep documentation sets in sync with the starter pack.

  • Added a header to the documentation to integrate the documentation (hosted on readthedocs) with the product website. The header can be customised with the product name and logo, and you can add custom links to the "More resources" section.

    See https://github.com/canonical/sphinx-docs-starter-pack#configure-the-header

  • Split the configuration file into a common conf.py file and a custom custom_conf.py file. All project-specific configuration should go into the custom_conf.py file, while the conf.py file should not be touched. This should make it easier to keep the configuration in sync with the starter pack.

Clone this wiki locally