Update the new Sphinx Stack

The Sphinx Stack is regularly updated to add features and address bugs. You can transfer these improvements to your project by following these steps:

  • Clone the latest version of the Sphinx Stack

  • Compare key files and directories in the Sphinx Stack to your project

  • Transfer or delete relevant changes

  • Confirm that your project builds correctly with the new changes

This guide assumes your project has minimal customizations, and the repository structure closely mirrors that of the Sphinx Stack. Depending on your customizations, you may need to take extra steps when updating.

Note

If canonical-sphinx is not included under extensions in your conf.py file, your project is not on an extension-based Sphinx Stack. Follow the guide on updating a legacy Sphinx Stack project.

Clone the Sphinx Stack repository

If you don’t have a clean, local copy of the Sphinx Stack, clone it:

git clone https://github.com/canonical/sphinx-stack.git

Confirm that the Sphinx Stack documentation and your project build with no errors.

Important

Verify that your project still builds correctly after each key step. This makes it easier to identify causes of build errors.

Update the configuration and build files

New Sphinx Stack versions often change the default configuration files. You’ll need to merge your project files with the config files from the new Sphinx Stack. The recommended approach is to copy the customizations in your project to the Sphinx Stack config files and then replace your project’s config files with those from the Sphinx Stack.

The changes to be made vary between projects and updates. Therefore, this guide cannot be overly prescriptive.

conf.py

Rename your conf.py file to avoid overwriting it, and copy the Sphinx Stack version to the same location. Use a graphical diff tool such as Kompare or meld to compare the old and new file and make the following changes:

  • Copy your standard project details to the new conf.py file. These include:

    • Project and author names

    • Ignored links

    • Social links, etc.

  • Verify that the /_static and /_templates directories are located at the locations specified by html_static_path and templates_path, respectively, in the new conf.py file. These should not be inside the /_dev directory.

For other customizations, consider need and compatibility before copying them to the new file. If it’s not obvious whether you should copy over a customization or include a new change, reach out to Canonical’s documentation team.

Makefile and .readthedocs.yaml

Depending on the version of your project’s Sphinx Stack, the new Makefile and .readthedocs.yaml files may have few or no changes. Apply the same approach you used for conf.py to merge your customizations into the new files.

If there are no project-specific customizations in your files but there are changes in the new ones, you can just overwrite your existing files with the new ones.

Update the _dev directory

In addition to the docs above, the /_dev directory is also likely to have some changes in each update. These files are not intended to be modified by users.

Unless you intentionally customized files in this directory, you can simply delete your project’s /_dev directory and replace it with the same directory from the Sphinx Stack. If there are modifications in your project’s /_dev directory, it is recommended that they transfer them out.

Review the remaining files

Some files in the Sphinx Stack may be updated less frequently, but it’s a good idea to review them during each update and determine if there are relevant changes:

  • Review requirements.txt: If there are any updates, and your project’s file has no repository-specific requirements, you can overwrite the existing file with the new one. If you added requirements based on your customizations, be sure to include them.

  • Review the workflows in the /.github directory: If there are changes in the following workflows, replace the existing files with the new ones. The Sphinx Stack will have other workflows as well, but you’ll need to decide whether your project needs them or not:

    • Automatic doc checks

    • CLA (contributor license agreement) check

    • Check for removed URLs

    • Markdown style check (only required for docs using markdown)

  • Review and transfer any necessary changes in the new .gitignore file to your project.

Build and test

Try building the docs locally and check the terminal output for errors:

make run

To ensure the updated docs will pass CI checks when you make a pull request, run the following commands and fix any errors reported:

  • make spelling

  • make linkcheck

  • make woke

  • make lint-md (if you included the markdown-style-checks workflow)

Troubleshooting errors

There is always the possibility of encountering build errors. Common causes include:

  • Incorrect file locations or file paths

  • Incompatible requirements in the new requirements file

  • Missing customizations

  • Cached build files

When troubleshooting use the make clean command to ensure cached versions of build files are not reused.

Clean up

There may be files that need to be deleted after the update such as Sphinx Stack files or files that have been replaced with newer versions:

  • If you haven’t done so already, delete the copies of conf.py, Makefile, and /.readthedocs.yaml that were renamed and replaced.

  • If you did not strictly follow this guide for this or previous updates, it’s possible that you have some Sphinx Stack files in your project. These files can be safely deleted:

    • .github/pull_request_template.md

    • .github/workflows/sphinx-python-dependency-build-checks.yml

    • .github/CODEOWNERS

    • .github/workflows/test-sphinx-stack.yml