Skip to content

Change log

Jump to bottom
Nick Veitch edited this page Jul 16, 2024 · 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.

2024/07/16

Updated the Vale helper script to correctly fetch the default vocabulary rules which were added to the style guide repository. In combination with an adjustment to the Vale action, this should solve issues with Vale-related errors.

2024/05/29

Added Vale functionality to the Makefile. The install target now installs the Vale pip package and the vale target retrieves Vale configuration files and runs against all MD, RST, and TXT files in the working directory.

2024/05/06

Abstracted the Makefile by introducing a Makefile.sp file that contains the actual targets and a Makefile that can be easily adapted to, for example, define different target names or add custom functionality.

2024/04/18

Added a contributors list to the bottom of each page, that shows the latest GitHub contributors for each file. This feature can be turned on/off through the display_contributors variable in custom_conf.py, and the time frame for committers can be specified through display_contributors_since.

2024/04/15

Added the watchfiles module to make make run work again after sphinx autobuild was updated.

2024/01/25

BREAKING CHANGE: A dependency management system was added. You can now opt-out of the extensions myst_parser, sphinx_reredirects, sphinxext.opengraph, sphinx_tabs.tabs, canonical.youtube-links, canonical.related-links, canonical.custom-rst-roles, canonical.terminal-output, notfound.extension.

Recommended actions:

  • Move custom required Python modules to the custom_required_modules array in the custom_conf.py file.
  • Delete the .sphinx/requirements.txt file. It will now get generated based on the configuration in custom_conf.py with make install.
  • Reinstall the local virtual Python environment with make clean && make install.
make clean
git commit .sphinx/requirements.txt
make install

See dd0ae84 for more details about how the dependency management system works.

2024/01/11

The shared workflow in canonical/documentation-workflows now runs the make pa11y accessibility check, but the check is optional and doesn't fail the workflow on error because older replicas of the starter pack won't have it available.

2024/01/09

Updated the font and font weights to look more like Vanilla.

2023/12/15

Added a 'make pa11y' Makefile target for running interactive CLI-based accessibility checks based on the pa11y toolset.

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