diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c848415..2e1fad8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,10 +6,10 @@ # Development reviewers # Adjust this once we establish a Sphinx development team. -* @akcano @dwilding @medubelko @minaelee @rkratky @SecondSkoll @tang-mm +* @a-velasco @dwilding @jahn-junior @medubelko @rkratky @SecondSkoll # Changes to CODEOWNERS must be reviewed by admins -/.github/CODEOWNERS @SecondSkoll +/.github/CODEOWNERS @jahn-junior @medubelko # Doc reviewers # /docs/ diff --git a/.github/workflows/test-starter-pack.yml b/.github/workflows/test-sphinx-stack.yml similarity index 85% rename from .github/workflows/test-starter-pack.yml rename to .github/workflows/test-sphinx-stack.yml index e50e4d8..bfbf503 100644 --- a/.github/workflows/test-starter-pack.yml +++ b/.github/workflows/test-sphinx-stack.yml @@ -1,7 +1,7 @@ -# This workflow tests the starter pack. -# Don't run this workflow on any repos that use the starter pack. +# This workflow tests the Sphinx Stack. +# Don't run this workflow on any repos that use the Sphinx Stack. -name: Test starter pack +name: Test Sphinx Stack on: push: @@ -10,7 +10,7 @@ on: jobs: test-docs: - name: Test on docs folder + name: Test on docs directory runs-on: ubuntu-latest steps: - name: Check out repo diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 1ccbcfa..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,233 +0,0 @@ -# sphinx-docs-starter-pack changelog - -## Upcoming - -* Separate default configuration for copyright and license statements. -* Fix the handling of non-zero exit codes from pymarkdownlnt. -* Add a how-to guide about testing the Ulwazi theme. -* Move the Python virtual environment from `docs/.sphinx/venv` to `docs/.venv`. -* Make rediraffe the default extension for page redirects -* Add default templates for the Canonical cookie banner and Google Analytics. -* Add an `AUTOBUILD_EXTRA_OPTS` variable to extend sphinx-autobuild options for `make run`. - -### Changed - -* `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562) -* `.github/workflows/check-removed-urls.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) -* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) -* `docs/.gitignore` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) -* `docs/.sphinx/.wordlist.txt` [#520](https://github.com/canonical/sphinx-docs-starter-pack/pull/520) -* `docs/conf.py` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558) -* `docs/Makefile` [#551](https://github.com/canonical/sphinx-docs-starter-pack/pull/551), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) -* `docs/redirects.txt` [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558) -* `docs/_templates/header.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549) -* `docs/_templates/footer.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549) - -## 1.5 - -* Add `CONTRIBUTING.md`. -* Rename Makefile variables to avoid collisions in host environment. -* Rename `TARGET` variable for Vale checks to `CHECK_PATH`. -* Remove or replace docs use of archived example product documentation site. -* Revert the switch to a reusable `automatic-doc-checks.yml` workflow. -* Add `-q` flag to linkchecker to only report errors or broken links. -* Update dependency canonical-sphinx to 0.6.0 or higher. -* Update the default runner version for markdown linting. - -### Changed - -* `docs/Makefile` [#494](https://github.com/canonical/sphinx-docs-starter-pack/pull/494), [#536](https://github.com/canonical/sphinx-docs-starter-pack/pull/536), [#544](https://github.com/canonical/sphinx-docs-starter-pack/pull/544) -* `docs/conf.py` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502), [#545](https://github.com/canonical/sphinx-docs-starter-pack/pull/545) -* `docs/how-to/guidance.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502) -* `docs/reference/index.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502) -* `docs/reference/myst-syntax-reference.md` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502) -* `docs/reference/rst-syntax-reference.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502) -* `.github/workflows/automatic-doc-checks.yml` [#514](https://github.com/canonical/sphinx-docs-starter-pack/pull/514) -* `.github/workflows/markdown-style-checks.yml [#535](https://github.com/canonical/sphinx-docs-starter-pack/pull/535) -* `docs/requirements.txt` [#543](https://github.com/canonical/sphinx-docs-starter-pack/pull/543) - -## 1.4.1 - -* Fix the version slug so the upgrade script has the right release tag. - -### Changed - -* `docs/.sphinx/version` [#516](https://github.com/canonical/sphinx-docs-starter-pack/pull/516) - -## 1.4.0 - -* Fix exclude paths issue for pymarkdown introduced in 0.9.35 and pin version. -* Add `install` dependency to `pymarkdownlnt-install` make target and use VENVDIR variable. -* Remove scripts and references to unused HTML metrics. -* Pin myst-parser package version to 4.0 to avoid conflicts. -* Make `BUILDDIR` in Makefile configurable from the calling environment. - -### Changed - -* `docs/requirements.txt` [#496](https://github.com/canonical/sphinx-docs-starter-pack/pull/496) -* `docs/Makefile` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490), [#504](https://github.com/canonical/sphinx-docs-starter-pack/pull/504), [#508](https://github.com/canonical/sphinx-docs-starter-pack/pull/508) -* `docs/.sphinx/update_sp.py` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490) - -### Removed - -* `docs/.sphinx/metrics/build_metrics.py` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490) -* `docs/.sphinx/metrics/source_metrics.sh` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490) - -## 1.3.1 - -* Switch doc links to `stable` slug. -* !!POTENTIAL CONFIGURATION ISSUE: Fixes duplicate version strings in sitemaps for versioned docs. This removes the `version` variable previously set in the sitemaps configuration section of `conf.py`. If you have any custom code that uses this variable elsewhere, do not remove it. -* Make `VALEDIR` in Makefile configurable from the calling environment. - -### Changed - -* `docs/conf.py` [#477](https://github.com/canonical/sphinx-docs-starter-pack/pull/477) -* `docs/Makefile` [#468](https://github.com/canonical/sphinx-docs-starter-pack/pull/468), [#472](https://github.com/canonical/sphinx-docs-starter-pack/pull/472) -* `.github/workflows/automatic-doc-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466) -* `.github/workflows/check-removed-urls.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466) -* `.github/workflows/markdown-style-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466) -* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466) -* `docs/Makefile` [#493](https://github.com/canonical/sphinx-docs-starter-pack/pull/493) - -## 1.3.0 - -* !!!BREAKING: Updated deps to use atomic extensions, not `canonical-sphinx[full]`. Updated `sphinx-terminal` uses backwards incompatible syntax -* Changed `html_baseurl` for better canonical URL support -* Changes metrics script to a less brittle Python script -* Introduce guidelines for adding diagrams-as-code -* Introduce guidelines for rendering CSV data as tables -* Introduce guidelines for pulling in docstrings using Sphinx `autodoc` extension -* Introduce guidelines for using custom base templates -* Dropped unused makefile variable `ALLFILES` -* Fix syntax error in Makefile that caused the fallback target to loop - infinitely. -* Add a step to the tutorial about removing `CODEOWNERS`. - -### Added - -* `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) - -## Changed - -* `docs/Makefile` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373), [#456](https://github.com/canonical/sphinx-docs-starter-pack/pull/456) -* `docs/requirements.txt` [#449](https://github.com/canonical/sphinx-docs-starter-pack/pull/449), [#456](https://github.com/canonical/sphinx-docs-starter-pack/pull/456), [#460](https://github.com/canonical/sphinx-docs-starter-pack/pull/460) -* `docs/conf.py` [#429](https://github.com/canonical/sphinx-docs-starter-pack/pull/429), [#449](https://github.com/canonical/sphinx-docs-starter-pack/pull/449), [#442](https://github.com/canonical/sphinx-docs-starter-pack/pull/442), [#460](https://github.com/canonical/sphinx-docs-starter-pack/pull/460) [#462](https://github.com/canonical/sphinx-docs-starter-pack/pull/462) -* `docs/.sphinx/get_vale_conf.py` [#448](https://github.com/canonical/sphinx-docs-starter-pack/pull/448) -* `docs/.sphinx/update_sp.py` [#425](https://github.com/canonical/sphinx-docs-starter-pack/pull/425) -* `docs/.sphinx/metrics/build_metrics.py` [#448](https://github.com/canonical/sphinx-docs-starter-pack/pull/448) -* `.github/workflows/check-removed-urls.yml` [#437](https://github.com/canonical/sphinx-docs-starter-pack/pull/437), [#445](https://github.com/canonical/sphinx-docs-starter-pack/pull/445) -* `.github/workflows/markdown-style-checks.yml` [#445](https://github.com/canonical/sphinx-docs-starter-pack/pull/445) -* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#445](https://github.com/canonical/sphinx-docs-starter-pack/pull/445) -* `.github/workflows/test-starter-pack.yml` [#445](https://github.com/canonical/sphinx-docs-starter-pack/pull/445) -* `docs/Makefile` [#461](https://github.com/canonical/sphinx-docs-starter-pack/pull/461) - -### Removed - -* `docs/.sphinx/metrics/build_metrics.sh` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) - -## 1.2.0 - -* Replaces spelling check with Vale. -* Fixes the Markdown linting GitHub action and adds a `make lint-md` check. -* Fixes the download branch name in the update script. -* Adds a check for removed URLs. - -### Added - -* `docs/.sphinx/.pymarkdown.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `.github/workflows/check-removed-urls.yml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) - -### Changed - -* `docs/.sphinx/update_sp.py` [#397](https://github.com/canonical/sphinx-docs-starter-pack/pull/397) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `.github/workflows/markdown-style-checks.yml` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `docs/Makefile` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/requirements.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/.sphinx/get_vale_conf.py` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) - -### Removed - -* `docs/.sphinx/.markdownlint.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `docs/.sphinx/.wordlist.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/.sphinx/spellingcheck.yaml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) - - -## 1.1.0 - -* Adds sitemap support. -* Simplifies vale binary download & install. -* Leaves vale install output in STDOUT to reveal potential problems. -* Improves update logic. -* Update Makefile logic - -### Changed - -* `docs/conf.py` [#389](https://github.com/canonical/sphinx-docs-starter-pack/pull/389) -* `docs/requirements.txt`(https://github.com/canonical/sphinx-docs-starter-pack/pull/389) - -## 1.0.1 - -Fixes an issue with Vale implementation, and adds words to main wordlist. - -### Changed - -* `docs/Makefile` [852c19b](https://github.com/canonical/sphinx-docs-starter-pack/commit/852c19bf162e4697d7f36b49e8bc36ad71302216) -* `docs/.sphinx/.wordlist.txt` [#367](https://github.com/canonical/sphinx-docs-starter-pack/pull/367) -* `docs/.sphinx/get_vale_conf.py` [#358](https://github.com/canonical/sphinx-docs-starter-pack/pull/358) - -## 1.0.0 - -First versioned release. Adds an update command to better facilitate updates to -starter pack based documentation sets. - -### Added - -* `CHANGELOG.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `.github/pull_request_template.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/version` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/update_sp.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) - -### Changed - -* `.readthedocs.yaml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/.markdownlint.json` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/Makefile` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/conf.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/requirements.txt` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) - -### Removed - -* `.wokeignore` [#363](https://github.com/canonical/sphinx-docs-starter-pack/pull/363) -* `docs/.sphinx/_static/project_specific.css` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) - -## pre-version - -This version is the initial versioned release, supporting the implementation of -updates. - -### Added - -* All files - -## VERSION - -{Summary of features} - -### Added - -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} - -### Changed - -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} - -### Removed - -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a17d8e2..c955ec5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,22 @@ -# Contributing to the Starter Pack +# Contributing to Sphinx Stack documentation -The Starter Pack provides a shared foundation for Sphinx documentation projects, and contributions help improve the documentation of all its users. The Documentation Practice team performs most of the work, but all contributors are welcome. +The Sphinx Stack is a shared foundation for Sphinx documentation projects, and +contributions help improve the documentation of all its users. The Documentation +Practice team performs most of the work, but all contributors are welcome. Common contributions include: - Bug fixes: Build errors, broken links, configuration issues -- Documentation: How-to guides on Starter Pack features and usage, syntax references, troubleshooting information -- Improvements: Better defaults, new extensions, workflow enhancements, new or improved style rules +- Improvements: Better defaults, new extensions, workflow enhancements, new or improved + style rules - Dependency updates: Security patches, compatibility fixes, better tooling -If you run into any problems or see room for improvement, we encourage you to open an issue or even contribute a fix. +If you run into any problems or see room for improvement, we encourage you to open an +issue or even contribute a fix. + +> This guide only covers contributions to documentation. If you're interested in +> contributing to Sphinx Stack development, refer to the [main repository's +> guide](https://github.com/canonical/sphinx-stack/blob/main/CONTRIBUTING.md). ## Review the project expectations @@ -17,62 +24,55 @@ Review these three documents before contributing: ### Ubuntu Code of Conduct -When contributing, you must abide by the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). Projects governed by Canonical expect good conduct and excellence from every member. +When contributing, you must abide by the [Ubuntu Code of +Conduct](https://ubuntu.com/community/ethos/code-of-conduct). Projects governed by +Canonical expect good conduct and excellence from every member. ### Canonical Contributor License Agreement -Code contributions can only be accepted from contributors who have signed our [Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors). Signing the agreement grants Canonical permission to use your contributions, and you remain the copyright owner of your work (no copyright assignment occurs). +Code contributions can only be accepted from contributors who have signed our +[Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors). Signing +the agreement grants Canonical permission to use your contributions, and you remain the +copyright owner of your work (no copyright assignment occurs). -Review the terms of the agreement before signing it or committing anything. If you agree and choose to sign it, your work can be incorporated into the repository. +Review the terms of the agreement before signing it or committing anything. If you agree +and choose to sign it, your work can be incorporated into the repository. ### Open source license -The Starter Pack is licensed under [GPL-3.0](LICENSE). Documentation for this project is licensed under CC-BY-SA 3.0. +The Sphinx Stack is licensed under [CC-BY-SA-3.0](LICENSE). ## Report an issue or open a request -If you find a bug or feature gap in the Starter Pack, look for it in the [project's GitHub issues](https://github.com/canonical/sphinx-docs-starter-pack/issues) first. Add your voice to the thread if you have fresh input. - -If the bug or feature doesn't have an issue, [open one](https://github.com/canonical/sphinx-docs-starter-pack/issues/new/choose). - -## What belongs in the Starter Pack - -The Starter Pack is designed to be a minimal, flexible foundation for diverse documentation projects. - -**Belongs in the Starter Pack:** -- Bug fixes for core functionality -- Improvements to default configuration that benefit all users -- Documentation about existing features -- Dependency updates for security or compatibility +If you find a bug or feature gap in the Sphinx Stack docs, look for it in the [project's +GitHub issues](https://github.com/canonical/sphinx-stack-docs/issues) first. Add +your voice to the thread if you have fresh input. -**May not belong in the Starter Pack:** -- Optional tooling or features (these should be opt-in and implemented by projects using the Starter Pack) -- Opinionated formatting or linting rules that would cause a sizable portion of existing doc sets to fail checks suddenly -- Changes that conflict with existing workflows -- Features that are project-specific rather than general-purpose -- UI-related changes may be better suited for the ongoing alternative theme update project (ask maintainers) - -When in doubt, open an issue first to discuss whether the change aligns with the project's goals. +If the bug or feature doesn't have an issue, [open +one](https://github.com/canonical/sphinx-stack-docs/issues/new/choose). ## Development setup -Create a [personal fork](https://github.com/canonical/sphinx-docs-starter-pack/fork) of the repository, then clone it and add the upstream remote: +Create a [personal fork](https://github.com/canonical/sphinx-stack-docs/fork) of +the repository, then clone it and add the upstream remote: -With [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account): +With +[SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account): ```bash -git clone git@github.com:/sphinx-docs-starter-pack -cd sphinx-docs-starter-pack -git remote add upstream git@github.com:canonical/sphinx-docs-starter-pack +git clone git@github.com:/sphinx-stack-docs +cd sphinx-stack-docs +git remote add upstream git@github.com:canonical/sphinx-stack-docs git fetch upstream ``` -With [HTTPS](https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls): +With +[HTTPS](https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls): ```bash -git clone https://github.com//sphinx-docs-starter-pack -cd sphinx-docs-starter-pack -git remote add upstream https://github.com/canonical/sphinx-docs-starter-pack +git clone https://github.com//sphinx-stack-docs +cd sphinx-stack-docs +git remote add upstream https://github.com/canonical/sphinx-stack-docs git fetch upstream ``` @@ -88,15 +88,20 @@ make html ### Research the topic -All significant work should be tied to an existing issue. Before starting, comment on the issue to have it assigned to you. +All significant work should be tied to an existing issue. Before starting, comment on +the issue to have it assigned to you. #### Minor changes -Check [GitHub issues](https://github.com/canonical/sphinx-docs-starter-pack/issues) for existing reports. If none exist, [open one](https://github.com/canonical/sphinx-docs-starter-pack/issues/new/choose) and state your interest in working on it. +Check [GitHub issues](https://github.com/canonical/sphinx-stack-docs/issues) for +existing reports. If none exist, [open +one](https://github.com/canonical/sphinx-stack-docs/issues/new/choose) and state +your interest in working on it. #### Major changes -Describe your proposal in the issue thread, including the plan, tests, and documentation. For new documentation pages, propose a [Diátaxis](https://diataxis.fr) category. +Describe your proposal in the issue thread, including page's +[Diátaxis](https://diataxis.fr) category and structure. ### Create a development branch @@ -107,15 +112,16 @@ git fetch upstream git checkout -b ``` -Name your branch `-` (e.g., `issue-235-add-string-sanitizer`), keeping it under 80 characters. +Name your branch `-` (e.g., `issue-235-add-setup-guide`), +keeping it under 80 characters. ### Make your changes Follow these guidelines: - Use separate commits for each logical change, and for changes to different components -- Keep the Starter Pack minimal by default; optional features are best implemented - by the projects using the Starter Pack rather than the Starter Pack itself +- Keep the Sphinx Stack minimal by default; optional features are best implemented + by the projects using the Sphinx Stack rather than the Sphinx Stack itself ### Commit a change @@ -127,14 +133,15 @@ git commit Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format: ``` -feat: add text sanitizer +docs: add initial setup guide ``` To determine the commit type, check the file history with `git log --oneline `. > **Tip** > -> If you're unsure which type to use, the commit may be doing too much, so split it into smaller commits instead. Select the highest-ranked type that fits: +> If you're unsure which type to use, the commit may be doing too much, so split it into +> smaller commits instead. Select the highest-ranked type that fits: > > - `ci` > - `build` @@ -149,34 +156,47 @@ To determine the commit type, check the file history with `git log --oneline **Tip** > -> You can configure your Git client to sign commits by default for any local repository by running `git config --global commit.gpgsign true`. Once you have done this, you no longer need to add `-S` to your commits explicitly. +> You can configure your Git client to sign commits by default for any local repository +> by running `git config --global commit.gpgsign true`. Once you have done this, you no +> longer need to add `-S` to your commits explicitly. > > See [GitHub Docs - Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) for more information. -If you've made an unsigned commit and encounter the "Commits must have verified signatures" error when pushing your changes to the remote: +If you've made an unsigned commit and encounter the "Commits must have verified +signatures" error when pushing your changes to the remote: -1. Amend the most recent commit by signing it without changing the commit message, and push again: +1. Amend the most recent commit by signing it without changing the commit message, and + push again: ```bash git commit --amend --no-edit -n -S git push ``` -2. If you still encounter the same error, confirm that your GitHub account has been set up properly to sign commits as described in the [GitHub Docs - About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). +2. If you still encounter the same error, confirm that your GitHub account has been set + up properly to sign commits as described in the [GitHub Docs - About commit signature + verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). > **Tip** > - > If you use SSH keys to sign your commits, make sure to add a "Signing Key" type in your GitHub account. See [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) for more information. + > If you use SSH keys to sign your commits, make sure to add a "Signing Key" type in + > your GitHub account. See [GitHub Docs - Adding a new SSH key to your + > account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) + > for more information. ### Test the change @@ -201,25 +221,14 @@ To preview locally with live reload at `http://127.0.0.1:8000`, run: make run ``` -### Document the change - -This documentation uses [Diátaxis](https://diataxis.fr). For small changes, update existing how-to guides and references. For major changes or new flows, create new pages in the appropriate category. - -Run the same basic checks locally that GitHub runs on PRs; see [Test the change](#test-the-change). - -#### Changelog guidance - -Doc-only changes generally do not require changelog entries. However, reviewers may request one for notable additions such as significant new how-to guides or reference documentation. - -For non-documentation changes, ensure that feature changes and fixes are documented in the relevant release notes. - ### Push the branch and open a PR ```bash git push -u origin ``` -Next, open a PR on GitHub. Format its title as a conventional commit (GitHub may do this automatically for single-commit branches). +Next, open a PR on GitHub. Format its title as a conventional commit (GitHub may do this +automatically for single-commit branches). ### Describing PRs @@ -228,16 +237,14 @@ Your PR should include the following details: - Title: Short, descriptive summary - Description: Problem solved, features added, or bugs fixed - Relevant issues: [Link related issues and PRs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) -- Testing: How reviewers can verify the change or test the fix -- Reversibility: For costly-to-reverse decisions, explain reasoning and reversal steps - -Make sure to peek at the preview for documentation changes (find the `Read the Docs build` check and click `...` - `View details`). If your PR adds or changes specific documentation pages, include links to the preview pages in the PR description. ## CI/CD pipeline -The repository configures multiple automated checks. Some are conditional based on target branch or changed files. +The repository configures multiple automated checks. Some are conditional based on +target branch or changed files. -If a check fails, review the logs for remediation guidance. For failures unrelated to your changes, rebase against the latest base branch. +If a check fails, review the logs for remediation guidance. For failures unrelated to +your changes, rebase against the latest base branch. ### Checks on all PRs @@ -256,20 +263,20 @@ These run on every PR and on pushes to `main`: #### CLA check in CI -When you open a pull request (PR) against the `main` branch, a mandatory automated check verifies that you have signed the CLA. It uses the [canonical/has-signed-canonical-cla](https://github.com/canonical/has-signed-canonical-cla) GitHub Action. +When you open a pull request (PR) against the `main` branch, a mandatory automated check +verifies that you have signed the CLA. It uses the +[canonical/has-signed-canonical-cla](https://github.com/canonical/has-signed-canonical-cla) +GitHub Action. If you haven't signed the CLA: 1. The check will fail with a message indicating the CLA requirement 2. Visit to review and sign the agreement -3. Once signed, re-run the check if you have permissions, or ask a maintainer to do so. Pushing a new commit also triggers re-evaluation. - -The CLA check only runs on PRs to `main`. Internal team members working on other branches should ensure they have signed the CLA before their changes are merged to `main`. - -### Checks on changes to `docs/` only +3. Once signed, re-run the check if you have permissions, or ask a maintainer to do so. + Pushing a new commit also triggers re-evaluation. -- Markdown style check: Runs `pymarkdownlnt` on Markdown files -- Automatic documentation checks: Runs upstream documentation workflow checks. - The project uses [canonical/documentation-workflows](https://github.com/canonical/documentation-workflows) for automatic documentation checks. To modify this part of CI behavior, pass inputs to upstream workflows rather than creating or customizing local copies. +The CLA check only runs on PRs to `main`. Internal team members working on other +branches should ensure they have signed the CLA before their changes are merged to +`main`. ### Optional checks (allowed to fail) @@ -282,27 +289,19 @@ PRs are typically reviewed within a week. ### Responding to feedback -Push additional commits to address feedback (commit locally rather than via GitHub UI to avoid sync conflicts). +Push additional commits to address feedback (commit locally rather than via GitHub UI to +avoid sync conflicts). -Rebase your branch before requesting a review to keep your commits clean. Once review has started, avoid rebasing to maintain the review history and make it easier for reviewers to see what changed. +Rebase your branch before requesting a review to keep your commits clean. Once review +has started, avoid rebasing to maintain the review history and make it easier for +reviewers to see what changed. ### Common feedback themes Reviewers may request: - Wording, terminology, or formatting changes -- Consistency with existing documentation patterns +- Consistency with existing patterns - Proper reST or MyST markup style -- Minimal examples before listing options -- Terminology: Align naming with existing documentation and code - Cross-references: Use proper reST or MyST syntax - Examples: Start minimal, then show options; include verification steps -- Theme compatibility: Test in both light and dark modes - -## Release process - - - -## Branch management policy - - diff --git a/LICENSE b/LICENSE index 31081ad..604209a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,694 +1,359 @@ -License for Canonical Starter Pack -================================== - -Unless otherwise stated, all code in this repository is licensed under -the following GPL license. -Documentation for this project is licensed under CC-BY-SA 3.0. - -Starter Pack code ------------------ - - GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The GNU General Public License is a free, copyleft license for -software and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains free -software for all its users. We, the Free Software Foundation, use the -GNU General Public License for most of our software; it applies also to -any other work released this way by its authors. You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you have -certain responsibilities if you distribute copies of the software, or if -you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the manufacturer -can do so. This is fundamentally incompatible with the aim of -protecting users' freedom to change the software. The systematic -pattern of such abuse occurs in the area of products for individuals to -use, which is precisely where it is most unacceptable. Therefore, we -have designed this version of the GPL to prohibit the practice for those -products. If such problems arise substantially in other domains, we -stand ready to extend this provision to those domains in future versions -of the GPL, as needed to protect the freedom of users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public License. - - "Copyright" also means copyright-like laws that apply to other kinds of -works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this -License. Each licensee is addressed as "you". "Licensees" and -"recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of an -exact copy. The resulting work is called a "modified version" of the -earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work based -on the Program. - - To "propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - - To "convey" a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user through -a computer network, with no transfer of a copy, is not conveying. - - An interactive user interface displays "Appropriate Legal Notices" -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work -for making modifications to it. "Object code" means any non-source -form of a work. - - A "Standard Interface" means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - - The "System Libraries" of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -"Major Component", in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - - The Corresponding Source need not include anything that users -can regenerate automatically from other parts of the Corresponding -Source. - - The Corresponding Source for a work in source code form is that -same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - - You may make, run and propagate covered works that you do not -convey, without conditions so long as your license otherwise remains -in force. You may convey covered works to others for the sole purpose -of having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply with -the terms of this License in conveying all material for which you do -not control copyright. Those thus making or running the covered works -for you must do so exclusively on your behalf, under your direction -and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under -the conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - - When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention -is effected by exercising rights under this License with respect to -the covered work, and you disclaim any intention to limit operation or -modification of the work as a means of enforcing, against the work's -users, your or third parties' legal rights to forbid circumvention of -technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these conditions: - - a) The work must carry prominent notices stating that you modified - it, and giving a relevant date. - - b) The work must carry prominent notices stating that it is - released under this License and any conditions added under section - 7. This requirement modifies the requirement in section 4 to - "keep intact all notices". - - c) You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable section 7 - additional terms, to the whole of the work, and all its parts, - regardless of how they are packaged. This License gives no - permission to license the work in any other way, but it does not - invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your - work need not make them do so. - - A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -"aggregate" if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms -of sections 4 and 5, provided that you also convey the -machine-readable Corresponding Source under the terms of this License, -in one of these ways: - - a) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for as - long as you offer spare parts or customer support for that product - model, to give anyone who possesses the object code either (1) a - copy of the Corresponding Source for all the software in the - product that is covered by this License, on a durable physical - medium customarily used for software interchange, for a price no - more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the - Corresponding Source from a network server at no charge. - - c) Convey individual copies of the object code with a copy of the - written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, and - only if you received the object code with such an offer, in accord - with subsection 6b. - - d) Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to - copy the object code is a network server, the Corresponding Source - may be on a different server (operated by you or a third party) - that supports equivalent copying facilities, provided you maintain - clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the - Corresponding Source, you remain obligated to ensure that it is - available for as long as needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided - you inform other peers where the object code and Corresponding - Source of the work are being offered to the general public at no - charge under subsection 6d. - - A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means any -tangible personal property which is normally used for personal, family, -or household purposes, or (2) anything designed or sold for incorporation -into a dwelling. In determining whether a product is a consumer product, -doubtful cases shall be resolved in favor of coverage. For a particular -product received by a particular user, "normally used" refers to a -typical or common use of that class of product, regardless of the status -of the particular user or of the way in which the particular user -actually uses, or expects or is expected to use, the product. A product -is a consumer product regardless of whether the product has substantial -commercial, industrial or non-consumer uses, unless such uses represent -the only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, -procedures, authorization keys, or other information required to install -and execute modified versions of a covered work in that User Product from -a modified version of its Corresponding Source. The information must -suffice to ensure that the continued functioning of the modified object -code is in no case prevented or interfered with solely because -modification has been made. - - If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - - The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates -for a work that has been modified or installed by the recipient, or for -the User Product in which it has been modified or installed. Access to a -network may be denied when the modification itself materially and -adversely affects the operation of the network or violates the rules and -protocols for communication across the network. - - Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - - When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders of -that material) supplement the terms of this License with terms: - - a) Disclaiming warranty or limiting liability differently from the - terms of sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or - author attributions in that material or in the Appropriate Legal - Notices displayed by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or - authors of the material; or - - e) Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified versions of - it) with contractual assumptions of liability to the recipient, for - any liability that these contractual assumptions directly impose on - those licensors and authors. - - All other non-permissive additional terms are considered "further -restrictions" within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - - If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; -the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - - However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the copyright -holder fails to notify you of the violation by some reasonable means -prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - - Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - - An "entity transaction" is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - - You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's "contributor version". - - A contributor's "essential patent claims" are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, "control" includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - - Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - - In the following three paragraphs, a "patent license" is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To "grant" such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - - If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. "Knowingly relying" means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - - A patent license is "discriminatory" if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make payment -to the third party based on the extent of your activity of conveying -the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory -patent license (a) in connection with copies of the covered work -conveyed by you (or copies made from those copies), or (b) primarily -for and in connection with specific products or compilations that -contain the covered work, unless you entered into that arrangement, -or that patent license was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey a -covered work so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you may -not convey it at all. For example, if you agree to terms that obligate you -to collect a royalty for further conveying from those to whom you convey -the Program, the only way you could satisfy both those terms and this -License would be to refrain entirely from conveying the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new versions of -the GNU General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - - Each version is given a distinguishing version number. If the -Program specifies that a certain numbered version of the GNU General -Public License "or any later version" applies to it, you have the -option of following the terms and conditions either of that numbered -version or of any later version published by the Free Software -Foundation. If the Program does not specify a version number of the -GNU General Public License, you may choose any version ever published -by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes you -to choose that version for the Program. - - Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY -OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM -IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF -ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE -USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF -DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), -EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF -SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - -Also add information on how to contact you by electronic and paper mail. - - If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - - Copyright (C) - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, your program's commands -might be different; for a GUI interface, you would use an "about box". - - You should also get your employer (if you work as a programmer) or school, -if any, to sign a "copyright disclaimer" for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -. - - The GNU General Public License does not permit incorporating your program -into proprietary programs. If your program is a subroutine library, you -may consider it more useful to permit linking proprietary applications with -the library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. But first, please read -. - -Starter Pack documentation --------------------------- - -Copyright 2024 Canonical Ltd. - -This work is licensed under the Creative Commons Attribution-Share Alike 3.0 -Unported License. To view a copy of this license, visit -http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative -Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. \ No newline at end of file +Creative Commons Legal Code + +Attribution-ShareAlike 3.0 Unported + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR + DAMAGES RESULTING FROM ITS USE. + +License + +THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE +COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY +COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS +AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. + +BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE +TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY +BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS +CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND +CONDITIONS. + +1. Definitions + + a. "Adaptation" means a work based upon the Work, or upon the Work and + other pre-existing works, such as a translation, adaptation, + derivative work, arrangement of music or other alterations of a + literary or artistic work, or phonogram or performance and includes + cinematographic adaptations or any other form in which the Work may be + recast, transformed, or adapted including in any form recognizably + derived from the original, except that a work that constitutes a + Collection will not be considered an Adaptation for the purpose of + this License. For the avoidance of doubt, where the Work is a musical + work, performance or phonogram, the synchronization of the Work in + timed-relation with a moving image ("synching") will be considered an + Adaptation for the purpose of this License. + b. "Collection" means a collection of literary or artistic works, such as + encyclopedias and anthologies, or performances, phonograms or + broadcasts, or other works or subject matter other than works listed + in Section 1(f) below, which, by reason of the selection and + arrangement of their contents, constitute intellectual creations, in + which the Work is included in its entirety in unmodified form along + with one or more other contributions, each constituting separate and + independent works in themselves, which together are assembled into a + collective whole. A work that constitutes a Collection will not be + considered an Adaptation (as defined below) for the purposes of this + License. + c. "Creative Commons Compatible License" means a license that is listed + at https://creativecommons.org/compatiblelicenses that has been + approved by Creative Commons as being essentially equivalent to this + License, including, at a minimum, because that license: (i) contains + terms that have the same purpose, meaning and effect as the License + Elements of this License; and, (ii) explicitly permits the relicensing + of adaptations of works made available under that license under this + License or a Creative Commons jurisdiction license with the same + License Elements as this License. + d. "Distribute" means to make available to the public the original and + copies of the Work or Adaptation, as appropriate, through sale or + other transfer of ownership. + e. "License Elements" means the following high-level license attributes + as selected by Licensor and indicated in the title of this License: + Attribution, ShareAlike. + f. "Licensor" means the individual, individuals, entity or entities that + offer(s) the Work under the terms of this License. + g. "Original Author" means, in the case of a literary or artistic work, + the individual, individuals, entity or entities who created the Work + or if no individual or entity can be identified, the publisher; and in + addition (i) in the case of a performance the actors, singers, + musicians, dancers, and other persons who act, sing, deliver, declaim, + play in, interpret or otherwise perform literary or artistic works or + expressions of folklore; (ii) in the case of a phonogram the producer + being the person or legal entity who first fixes the sounds of a + performance or other sounds; and, (iii) in the case of broadcasts, the + organization that transmits the broadcast. + h. "Work" means the literary and/or artistic work offered under the terms + of this License including without limitation any production in the + literary, scientific and artistic domain, whatever may be the mode or + form of its expression including digital form, such as a book, + pamphlet and other writing; a lecture, address, sermon or other work + of the same nature; a dramatic or dramatico-musical work; a + choreographic work or entertainment in dumb show; a musical + composition with or without words; a cinematographic work to which are + assimilated works expressed by a process analogous to cinematography; + a work of drawing, painting, architecture, sculpture, engraving or + lithography; a photographic work to which are assimilated works + expressed by a process analogous to photography; a work of applied + art; an illustration, map, plan, sketch or three-dimensional work + relative to geography, topography, architecture or science; a + performance; a broadcast; a phonogram; a compilation of data to the + extent it is protected as a copyrightable work; or a work performed by + a variety or circus performer to the extent it is not otherwise + considered a literary or artistic work. + i. "You" means an individual or entity exercising rights under this + License who has not previously violated the terms of this License with + respect to the Work, or who has received express permission from the + Licensor to exercise rights under this License despite a previous + violation. + j. "Publicly Perform" means to perform public recitations of the Work and + to communicate to the public those public recitations, by any means or + process, including by wire or wireless means or public digital + performances; to make available to the public Works in such a way that + members of the public may access these Works from a place and at a + place individually chosen by them; to perform the Work to the public + by any means or process and the communication to the public of the + performances of the Work, including by public digital performance; to + broadcast and rebroadcast the Work by any means including signs, + sounds or images. + k. "Reproduce" means to make copies of the Work by any means including + without limitation by sound or visual recordings and the right of + fixation and reproducing fixations of the Work, including storage of a + protected performance or phonogram in digital form or other electronic + medium. + +2. Fair Dealing Rights. Nothing in this License is intended to reduce, +limit, or restrict any uses free from copyright or rights arising from +limitations or exceptions that are provided for in connection with the +copyright protection under copyright law or other applicable laws. + +3. License Grant. Subject to the terms and conditions of this License, +Licensor hereby grants You a worldwide, royalty-free, non-exclusive, +perpetual (for the duration of the applicable copyright) license to +exercise the rights in the Work as stated below: + + a. to Reproduce the Work, to incorporate the Work into one or more + Collections, and to Reproduce the Work as incorporated in the + Collections; + b. to create and Reproduce Adaptations provided that any such Adaptation, + including any translation in any medium, takes reasonable steps to + clearly label, demarcate or otherwise identify that changes were made + to the original Work. For example, a translation could be marked "The + original work was translated from English to Spanish," or a + modification could indicate "The original work has been modified."; + c. to Distribute and Publicly Perform the Work including as incorporated + in Collections; and, + d. to Distribute and Publicly Perform Adaptations. + e. For the avoidance of doubt: + + i. Non-waivable Compulsory License Schemes. In those jurisdictions in + which the right to collect royalties through any statutory or + compulsory licensing scheme cannot be waived, the Licensor + reserves the exclusive right to collect such royalties for any + exercise by You of the rights granted under this License; + ii. Waivable Compulsory License Schemes. In those jurisdictions in + which the right to collect royalties through any statutory or + compulsory licensing scheme can be waived, the Licensor waives the + exclusive right to collect such royalties for any exercise by You + of the rights granted under this License; and, + iii. Voluntary License Schemes. The Licensor waives the right to + collect royalties, whether individually or, in the event that the + Licensor is a member of a collecting society that administers + voluntary licensing schemes, via that society, from any exercise + by You of the rights granted under this License. + +The above rights may be exercised in all media and formats whether now +known or hereafter devised. The above rights include the right to make +such modifications as are technically necessary to exercise the rights in +other media and formats. Subject to Section 8(f), all rights not expressly +granted by Licensor are hereby reserved. + +4. Restrictions. The license granted in Section 3 above is expressly made +subject to and limited by the following restrictions: + + a. You may Distribute or Publicly Perform the Work only under the terms + of this License. You must include a copy of, or the Uniform Resource + Identifier (URI) for, this License with every copy of the Work You + Distribute or Publicly Perform. You may not offer or impose any terms + on the Work that restrict the terms of this License or the ability of + the recipient of the Work to exercise the rights granted to that + recipient under the terms of the License. You may not sublicense the + Work. You must keep intact all notices that refer to this License and + to the disclaimer of warranties with every copy of the Work You + Distribute or Publicly Perform. When You Distribute or Publicly + Perform the Work, You may not impose any effective technological + measures on the Work that restrict the ability of a recipient of the + Work from You to exercise the rights granted to that recipient under + the terms of the License. This Section 4(a) applies to the Work as + incorporated in a Collection, but this does not require the Collection + apart from the Work itself to be made subject to the terms of this + License. If You create a Collection, upon notice from any Licensor You + must, to the extent practicable, remove from the Collection any credit + as required by Section 4(c), as requested. If You create an + Adaptation, upon notice from any Licensor You must, to the extent + practicable, remove from the Adaptation any credit as required by + Section 4(c), as requested. + b. You may Distribute or Publicly Perform an Adaptation only under the + terms of: (i) this License; (ii) a later version of this License with + the same License Elements as this License; (iii) a Creative Commons + jurisdiction license (either this or a later license version) that + contains the same License Elements as this License (e.g., + Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible + License. If you license the Adaptation under one of the licenses + mentioned in (iv), you must comply with the terms of that license. If + you license the Adaptation under the terms of any of the licenses + mentioned in (i), (ii) or (iii) (the "Applicable License"), you must + comply with the terms of the Applicable License generally and the + following provisions: (I) You must include a copy of, or the URI for, + the Applicable License with every copy of each Adaptation You + Distribute or Publicly Perform; (II) You may not offer or impose any + terms on the Adaptation that restrict the terms of the Applicable + License or the ability of the recipient of the Adaptation to exercise + the rights granted to that recipient under the terms of the Applicable + License; (III) You must keep intact all notices that refer to the + Applicable License and to the disclaimer of warranties with every copy + of the Work as included in the Adaptation You Distribute or Publicly + Perform; (IV) when You Distribute or Publicly Perform the Adaptation, + You may not impose any effective technological measures on the + Adaptation that restrict the ability of a recipient of the Adaptation + from You to exercise the rights granted to that recipient under the + terms of the Applicable License. This Section 4(b) applies to the + Adaptation as incorporated in a Collection, but this does not require + the Collection apart from the Adaptation itself to be made subject to + the terms of the Applicable License. + c. If You Distribute, or Publicly Perform the Work or any Adaptations or + Collections, You must, unless a request has been made pursuant to + Section 4(a), keep intact all copyright notices for the Work and + provide, reasonable to the medium or means You are utilizing: (i) the + name of the Original Author (or pseudonym, if applicable) if supplied, + and/or if the Original Author and/or Licensor designate another party + or parties (e.g., a sponsor institute, publishing entity, journal) for + attribution ("Attribution Parties") in Licensor's copyright notice, + terms of service or by other reasonable means, the name of such party + or parties; (ii) the title of the Work if supplied; (iii) to the + extent reasonably practicable, the URI, if any, that Licensor + specifies to be associated with the Work, unless such URI does not + refer to the copyright notice or licensing information for the Work; + and (iv) , consistent with Ssection 3(b), in the case of an + Adaptation, a credit identifying the use of the Work in the Adaptation + (e.g., "French translation of the Work by Original Author," or + "Screenplay based on original Work by Original Author"). The credit + required by this Section 4(c) may be implemented in any reasonable + manner; provided, however, that in the case of a Adaptation or + Collection, at a minimum such credit will appear, if a credit for all + contributing authors of the Adaptation or Collection appears, then as + part of these credits and in a manner at least as prominent as the + credits for the other contributing authors. For the avoidance of + doubt, You may only use the credit required by this Section for the + purpose of attribution in the manner set out above and, by exercising + Your rights under this License, You may not implicitly or explicitly + assert or imply any connection with, sponsorship or endorsement by the + Original Author, Licensor and/or Attribution Parties, as appropriate, + of You or Your use of the Work, without the separate, express prior + written permission of the Original Author, Licensor and/or Attribution + Parties. + d. Except as otherwise agreed in writing by the Licensor or as may be + otherwise permitted by applicable law, if You Reproduce, Distribute or + Publicly Perform the Work either by itself or as part of any + Adaptations or Collections, You must not distort, mutilate, modify or + take other derogatory action in relation to the Work which would be + prejudicial to the Original Author's honor or reputation. Licensor + agrees that in those jurisdictions (e.g. Japan), in which any exercise + of the right granted in Section 3(b) of this License (the right to + make Adaptations) would be deemed to be a distortion, mutilation, + modification or other derogatory action prejudicial to the Original + Author's honor and reputation, the Licensor will waive or not assert, + as appropriate, this Section, to the fullest extent permitted by the + applicable national law, to enable You to reasonably exercise Your + right under Section 3(b) of this License (right to make Adaptations) + but not otherwise. + +5. Representations, Warranties and Disclaimer + +UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR +OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY +KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, +INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, +FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF +LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, +WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION +OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. + +6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE +LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR +ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES +ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS +BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +7. Termination + + a. This License and the rights granted hereunder will terminate + automatically upon any breach by You of the terms of this License. + Individuals or entities who have received Adaptations or Collections + from You under this License, however, will not have their licenses + terminated provided such individuals or entities remain in full + compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will + survive any termination of this License. + b. Subject to the above terms and conditions, the license granted here is + perpetual (for the duration of the applicable copyright in the Work). + Notwithstanding the above, Licensor reserves the right to release the + Work under different license terms or to stop distributing the Work at + any time; provided, however that any such election will not serve to + withdraw this License (or any other license that has been, or is + required to be, granted under the terms of this License), and this + License will continue in full force and effect unless terminated as + stated above. + +8. Miscellaneous + + a. Each time You Distribute or Publicly Perform the Work or a Collection, + the Licensor offers to the recipient a license to the Work on the same + terms and conditions as the license granted to You under this License. + b. Each time You Distribute or Publicly Perform an Adaptation, Licensor + offers to the recipient a license to the original Work on the same + terms and conditions as the license granted to You under this License. + c. If any provision of this License is invalid or unenforceable under + applicable law, it shall not affect the validity or enforceability of + the remainder of the terms of this License, and without further action + by the parties to this agreement, such provision shall be reformed to + the minimum extent necessary to make such provision valid and + enforceable. + d. No term or provision of this License shall be deemed waived and no + breach consented to unless such waiver or consent shall be in writing + and signed by the party to be charged with such waiver or consent. + e. This License constitutes the entire agreement between the parties with + respect to the Work licensed here. There are no understandings, + agreements or representations with respect to the Work not specified + here. Licensor shall not be bound by any additional provisions that + may appear in any communication from You. This License may not be + modified without the mutual written agreement of the Licensor and You. + f. The rights granted under, and the subject matter referenced, in this + License were drafted utilizing the terminology of the Berne Convention + for the Protection of Literary and Artistic Works (as amended on + September 28, 1979), the Rome Convention of 1961, the WIPO Copyright + Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 + and the Universal Copyright Convention (as revised on July 24, 1971). + These rights and subject matter take effect in the relevant + jurisdiction in which the License terms are sought to be enforced + according to the corresponding provisions of the implementation of + those treaty provisions in the applicable national law. If the + standard suite of rights granted under applicable copyright law + includes additional rights not granted under this License, such + additional rights are deemed to be included in the License; this + License is not intended to restrict the license of any rights under + applicable law. + + +Creative Commons Notice + + Creative Commons is not a party to this License, and makes no warranty + whatsoever in connection with the Work. Creative Commons will not be + liable to You or any party on any legal theory for any damages + whatsoever, including without limitation any general, special, + incidental or consequential damages arising in connection to this + license. Notwithstanding the foregoing two (2) sentences, if Creative + Commons has expressly identified itself as the Licensor hereunder, it + shall have all rights and obligations of Licensor. + + Except for the limited purpose of indicating to the public that the + Work is licensed under the CCPL, Creative Commons does not authorize + the use by either party of the trademark "Creative Commons" or any + related trademark or logo of Creative Commons without the prior + written consent of Creative Commons. Any permitted use will be in + compliance with Creative Commons' then-current trademark usage + guidelines, as may be published on its website or otherwise made + available upon request from time to time. For the avoidance of doubt, + this trademark restriction does not form part of the License. + + Creative Commons may be contacted at https://creativecommons.org/. diff --git a/README.md b/README.md index 526c7d5..5c2f3a7 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,20 @@ -# Canonical's Sphinx Starter Pack +# Sphinx Stack documentation -*A pre-configured repository to build and publish documentation with Sphinx.* +User documentation for the [Sphinx +Stack](https://github.com/canonical/sphinx-stack) — a set of tools for +building and publishing Sphinx documentation. -## Description - -The Documentation Starter Pack includes: - -* A bundled [Sphinx] theme, configuration, and extensions -* Support for both reStructuredText (reST) and MyST Markdown -* Build checks for links, spelling, and inclusive language -* Customisation support layered over a core configuration - -See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/ - -## Structure - -This section outlines the structure of this repository, and some key files. - -### `docs/` - -This directory contains the documentation for the Starter Pack itself. - -To view it in your browser, navigate to this directory and type `make run`. - -### `.github/workflows/` - -This directory contains files used for documentation build checks via GitHub's CI. - -The file `test-starter-pack.yml` tests the functionality of the Starter Pack project. +The template itself can be found at +[canonical/sphinx-stack](https://github.com/canonical/sphinx-stack). ## Contributing -We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request. +We welcome contributions to this project! If you have suggestions, bug fixes, or +improvements, please open an issue or submit a pull request. -Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs). +Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any +changes. The agreement grants Canonical permission to use your contributions. The author +of a change remains the copyright owner of their code (no copyright assignment occurs). diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 08e6477..529c24a 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -20,6 +20,7 @@ Kompare lang LaTeX latexmk +LLMs? Multipass npm otf @@ -27,6 +28,7 @@ plantuml PNG Pygments pymarkdown +pymarkdownlnt QEMU Rockcraft readthedocs diff --git a/docs/.gitignore b/docs/.gitignore index 46b2984..3006f13 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -3,15 +3,15 @@ .venv/ # Sphinx -.sphinx/warnings.txt -.sphinx/.wordlist.dic -.sphinx/.doctrees/ -.sphinx/update/ -.sphinx/node_modules/ +_dev/warnings.txt +_dev/.wordlist.dic +_dev/.doctrees/ +_dev/update/ +_dev/node_modules/ # Vale -.sphinx/styles/* -.sphinx/vale.ini +_dev/styles/* +_dev/vale.ini # Build outputs _build diff --git a/docs/.sphinx/version b/docs/.sphinx/version deleted file mode 100644 index 810ee4e..0000000 --- a/docs/.sphinx/version +++ /dev/null @@ -1 +0,0 @@ -1.6 diff --git a/docs/Makefile b/docs/Makefile index 7415195..18d97e6 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,21 +5,21 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINX_DIR ?= .sphinx -SPHINX_OPTS ?= -c . -d $(SPHINX_DIR)/.doctrees -j auto +DEV_DIR ?= _dev +SPHINX_OPTS ?= -c . -d $(DEV_DIR)/.doctrees -j auto SPHINX_BUILD ?= $(DOCS_VENVDIR)/bin/sphinx-build SPHINX_HOST ?= 127.0.0.1 SPHINX_PORT ?= 8000 -SPHINX_AUTOBUILD_OPTS ?= +SPHINX_AUTOBUILD_OPTS ?= -D=llms_txt_enabled=0 DOCS_VENVDIR ?= .venv DOCS_VENV ?= $(DOCS_VENVDIR)/bin/activate DOCS_SOURCEDIR ?= . DOCS_BUILDDIR ?= _build DOCS_PDFPACKAGES ?= latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng -DOCS_VOCAB ?= $(SPHINX_DIR)/styles/config/vocabularies/Canonical +DOCS_VOCAB ?= $(DEV_DIR)/styles/config/vocabularies/Canonical VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale -VALE_CONFIG ?= $(SPHINX_DIR)/vale.ini -PA11Y_CMD ?= $(SPHINX_DIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINX_DIR)/pa11y.json +VALE_CONFIG ?= $(DEV_DIR)/vale.ini +PA11Y_CMD ?= $(DEV_DIR)/node_modules/pa11y/bin/pa11y.js --config $(DEV_DIR)/pa11y.json CONFIRM_SUDO ?= N CHECK_PATH ?= $(filter-out $(DOCS_VENVDIR),$(wildcard *)) @@ -69,8 +69,8 @@ $(DOCS_VENVDIR): pa11y-install: @command -v $(PA11Y_CMD) >/dev/null || { \ echo "Installing \"pa11y\" from npm..."; echo; \ - mkdir -p $(SPHINX_DIR)/node_modules/ ; \ - npm install --prefix $(SPHINX_DIR) pa11y; \ + mkdir -p $(DEV_DIR)/node_modules/ ; \ + npm install --prefix $(DEV_DIR) pa11y; \ } pymarkdownlnt-install: install @@ -79,14 +79,14 @@ pymarkdownlnt-install: install install: $(DOCS_VENVDIR) run: install - . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(SPHINX_AUTOBUILD_OPTS) + . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(SPHINX_AUTOBUILD_OPTS) # Does not depend on $(DOCS_BUILDDIR) to rebuild properly at every run. html: install - . $(DOCS_VENV); $(SPHINX_BUILD) --fail-on-warning --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) + . $(DOCS_VENV); $(SPHINX_BUILD) --fail-on-warning --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(DEV_DIR)/warnings.txt $(SPHINX_OPTS) epub: install - . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) + . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(DEV_DIR)/warnings.txt $(SPHINX_OPTS) serve: html cd "$(DOCS_BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT) @@ -94,13 +94,13 @@ serve: html clean: clean-doc @test ! -e "$(DOCS_VENVDIR)" -o -d "$(DOCS_VENVDIR)" -a "$(abspath $(DOCS_VENVDIR))" != "$(DOCS_VENVDIR)" rm -rf $(DOCS_VENVDIR) - rm -rf $(SPHINX_DIR)/node_modules/ - rm -rf $(SPHINX_DIR)/styles + rm -rf $(DEV_DIR)/node_modules/ + rm -rf $(DEV_DIR)/styles rm -rf $(VALE_CONFIG) clean-doc: git clean -fx "$(DOCS_BUILDDIR)" - rm -rf $(SPHINX_DIR)/.doctrees + rm -rf $(DEV_DIR)/.doctrees linkcheck: install . $(DOCS_VENV) ; $(SPHINX_BUILD) -b linkcheck -q "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) || { grep --color -F "[broken]" "$(DOCS_BUILDDIR)/output.txt"; exit 1; } @@ -114,11 +114,11 @@ pa11y: pa11y-install html # which should not result in failure lint-md: pymarkdownlnt-install @. $(DOCS_VENV); pymarkdownlnt \ - --config $(SPHINX_DIR)/.pymarkdown.json \ + --config $(DEV_DIR)/.pymarkdown.json \ --return-code-scheme explicit \ scan \ --recurse \ - --exclude=$(SPHINX_DIR)/** \ + --exclude=$(DEV_DIR)/** \ --exclude=$(DOCS_VENVDIR)/** \ $(DOCS_SOURCEDIR); \ status=$$?; \ @@ -130,31 +130,31 @@ lint-md: pymarkdownlnt-install exit $$status; vale-install: install - @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(SPHINX_DIR)/get_vale_conf.py - @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINX_DIR)/styles/woke.filter - @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/error.filter - @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/spelling.filter + @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(DEV_DIR)/get_vale_conf.py + @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(DEV_DIR)/styles/woke.filter + @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(DEV_DIR)/styles/error.filter + @echo '.Name=="Canonical.000-US-spellcheck"' > $(DEV_DIR)/styles/spelling.filter @. $(DOCS_VENV); find $(VALE_DIR)/vale_bin -size 195c -exec vale --version \; woke: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale acceptable term check against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt vale: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt spelling: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt spellcheck: spelling @@ -183,7 +183,7 @@ pdf: pdf-prep @echo update: install - @. $(DOCS_VENV); .sphinx/update_sp.py + @. $(DOCS_VENV); $(DEV_DIR)/update_sp.py # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINX_OPTS). diff --git a/docs/_dev/.doctrees/contribute/index.doctree b/docs/_dev/.doctrees/contribute/index.doctree new file mode 100644 index 0000000..ec084ef Binary files /dev/null and b/docs/_dev/.doctrees/contribute/index.doctree differ diff --git a/docs/_dev/.doctrees/contribute/test-ulwazi-theme.doctree b/docs/_dev/.doctrees/contribute/test-ulwazi-theme.doctree new file mode 100644 index 0000000..43477c4 Binary files /dev/null and b/docs/_dev/.doctrees/contribute/test-ulwazi-theme.doctree differ diff --git a/docs/_dev/.doctrees/environment.pickle b/docs/_dev/.doctrees/environment.pickle new file mode 100644 index 0000000..0c48dd8 Binary files /dev/null and b/docs/_dev/.doctrees/environment.pickle differ diff --git a/docs/_dev/.doctrees/explanation/build.doctree b/docs/_dev/.doctrees/explanation/build.doctree new file mode 100644 index 0000000..62e7801 Binary files /dev/null and b/docs/_dev/.doctrees/explanation/build.doctree differ diff --git a/docs/_dev/.doctrees/explanation/components.doctree b/docs/_dev/.doctrees/explanation/components.doctree new file mode 100644 index 0000000..e8ba4cc Binary files /dev/null and b/docs/_dev/.doctrees/explanation/components.doctree differ diff --git a/docs/_dev/.doctrees/explanation/index.doctree b/docs/_dev/.doctrees/explanation/index.doctree new file mode 100644 index 0000000..0f750a2 Binary files /dev/null and b/docs/_dev/.doctrees/explanation/index.doctree differ diff --git a/docs/_dev/.doctrees/explanation/sitemaps.doctree b/docs/_dev/.doctrees/explanation/sitemaps.doctree new file mode 100644 index 0000000..503f4db Binary files /dev/null and b/docs/_dev/.doctrees/explanation/sitemaps.doctree differ diff --git a/docs/_dev/.doctrees/how-to/build-and-preview.doctree b/docs/_dev/.doctrees/how-to/build-and-preview.doctree new file mode 100644 index 0000000..3785324 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/build-and-preview.doctree differ diff --git a/docs/_dev/.doctrees/how-to/configure-your-project.doctree b/docs/_dev/.doctrees/how-to/configure-your-project.doctree new file mode 100644 index 0000000..b58d350 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/configure-your-project.doctree differ diff --git a/docs/_dev/.doctrees/how-to/index.doctree b/docs/_dev/.doctrees/how-to/index.doctree new file mode 100644 index 0000000..6dc3339 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/index.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/add-documentation-testing.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/add-documentation-testing.doctree new file mode 100644 index 0000000..085be48 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/add-documentation-testing.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/bridge-project-and-docs-builds.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/bridge-project-and-docs-builds.doctree new file mode 100644 index 0000000..b82aa52 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/bridge-project-and-docs-builds.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/custom-html-templates.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/custom-html-templates.doctree new file mode 100644 index 0000000..8a515cb Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/custom-html-templates.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/customise-pdf.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/customise-pdf.doctree new file mode 100644 index 0000000..5eaef3a Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/customise-pdf.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/enable-google-analytics.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/enable-google-analytics.doctree new file mode 100644 index 0000000..5159b1e Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/enable-google-analytics.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/external-referencing-intersphinx.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/external-referencing-intersphinx.doctree new file mode 100644 index 0000000..b6669c3 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/external-referencing-intersphinx.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/index.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/index.doctree new file mode 100644 index 0000000..8c80c75 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/index.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/interactive-tables.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/interactive-tables.doctree new file mode 100644 index 0000000..410a4cd Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/interactive-tables.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/mermaid-diagrams.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/mermaid-diagrams.doctree new file mode 100644 index 0000000..c26bd3f Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/mermaid-diagrams.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/openapi-specifications.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/openapi-specifications.doctree new file mode 100644 index 0000000..03972df Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/openapi-specifications.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/python-docstrings.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/python-docstrings.doctree new file mode 100644 index 0000000..15b9645 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/python-docstrings.doctree differ diff --git a/docs/_dev/.doctrees/how-to/optional-customisation/redirect-pages.doctree b/docs/_dev/.doctrees/how-to/optional-customisation/redirect-pages.doctree new file mode 100644 index 0000000..a92b331 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/optional-customisation/redirect-pages.doctree differ diff --git a/docs/_dev/.doctrees/how-to/publish-on-rtd.doctree b/docs/_dev/.doctrees/how-to/publish-on-rtd.doctree new file mode 100644 index 0000000..4fd3daa Binary files /dev/null and b/docs/_dev/.doctrees/how-to/publish-on-rtd.doctree differ diff --git a/docs/_dev/.doctrees/how-to/run-documentation-checks.doctree b/docs/_dev/.doctrees/how-to/run-documentation-checks.doctree new file mode 100644 index 0000000..9b747c6 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/run-documentation-checks.doctree differ diff --git a/docs/_dev/.doctrees/how-to/troubleshooting.doctree b/docs/_dev/.doctrees/how-to/troubleshooting.doctree new file mode 100644 index 0000000..6b14905 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/troubleshooting.doctree differ diff --git a/docs/_dev/.doctrees/how-to/update-sphinx-stack/index.doctree b/docs/_dev/.doctrees/how-to/update-sphinx-stack/index.doctree new file mode 100644 index 0000000..3a0dc31 Binary files /dev/null and b/docs/_dev/.doctrees/how-to/update-sphinx-stack/index.doctree differ diff --git a/docs/_dev/.doctrees/how-to/update-sphinx-stack/legacy-sphinx-stack.doctree b/docs/_dev/.doctrees/how-to/update-sphinx-stack/legacy-sphinx-stack.doctree new file mode 100644 index 0000000..b70883d Binary files /dev/null and b/docs/_dev/.doctrees/how-to/update-sphinx-stack/legacy-sphinx-stack.doctree differ diff --git a/docs/_dev/.doctrees/how-to/update-sphinx-stack/new-sphinx-stack.doctree b/docs/_dev/.doctrees/how-to/update-sphinx-stack/new-sphinx-stack.doctree new file mode 100644 index 0000000..0bfce9a Binary files /dev/null and b/docs/_dev/.doctrees/how-to/update-sphinx-stack/new-sphinx-stack.doctree differ diff --git a/docs/_dev/.doctrees/index.doctree b/docs/_dev/.doctrees/index.doctree new file mode 100644 index 0000000..0cc8446 Binary files /dev/null and b/docs/_dev/.doctrees/index.doctree differ diff --git a/docs/_dev/.doctrees/reference/default-extensions.doctree b/docs/_dev/.doctrees/reference/default-extensions.doctree new file mode 100644 index 0000000..b84ce90 Binary files /dev/null and b/docs/_dev/.doctrees/reference/default-extensions.doctree differ diff --git a/docs/_dev/.doctrees/reference/github-workflows.doctree b/docs/_dev/.doctrees/reference/github-workflows.doctree new file mode 100644 index 0000000..09d4650 Binary files /dev/null and b/docs/_dev/.doctrees/reference/github-workflows.doctree differ diff --git a/docs/_dev/.doctrees/reference/index.doctree b/docs/_dev/.doctrees/reference/index.doctree new file mode 100644 index 0000000..43a56f2 Binary files /dev/null and b/docs/_dev/.doctrees/reference/index.doctree differ diff --git a/docs/_dev/.doctrees/reference/myst-syntax.doctree b/docs/_dev/.doctrees/reference/myst-syntax.doctree new file mode 100644 index 0000000..23b131d Binary files /dev/null and b/docs/_dev/.doctrees/reference/myst-syntax.doctree differ diff --git a/docs/_dev/.doctrees/reference/rst-syntax.doctree b/docs/_dev/.doctrees/reference/rst-syntax.doctree new file mode 100644 index 0000000..697ef2c Binary files /dev/null and b/docs/_dev/.doctrees/reference/rst-syntax.doctree differ diff --git a/docs/_dev/.doctrees/release-notes/1.4.doctree b/docs/_dev/.doctrees/release-notes/1.4.doctree new file mode 100644 index 0000000..6919c9c Binary files /dev/null and b/docs/_dev/.doctrees/release-notes/1.4.doctree differ diff --git a/docs/_dev/.doctrees/release-notes/1.5.doctree b/docs/_dev/.doctrees/release-notes/1.5.doctree new file mode 100644 index 0000000..73175f3 Binary files /dev/null and b/docs/_dev/.doctrees/release-notes/1.5.doctree differ diff --git a/docs/_dev/.doctrees/release-notes/1.6.doctree b/docs/_dev/.doctrees/release-notes/1.6.doctree new file mode 100644 index 0000000..264fed7 Binary files /dev/null and b/docs/_dev/.doctrees/release-notes/1.6.doctree differ diff --git a/docs/_dev/.doctrees/release-notes/index.doctree b/docs/_dev/.doctrees/release-notes/index.doctree new file mode 100644 index 0000000..6fdf276 Binary files /dev/null and b/docs/_dev/.doctrees/release-notes/index.doctree differ diff --git a/docs/_dev/.doctrees/set-up-a-new-project.doctree b/docs/_dev/.doctrees/set-up-a-new-project.doctree new file mode 100644 index 0000000..928908c Binary files /dev/null and b/docs/_dev/.doctrees/set-up-a-new-project.doctree differ diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/_dev/.pre-commit-config.yaml similarity index 100% rename from docs/.sphinx/.pre-commit-config.yaml rename to docs/_dev/.pre-commit-config.yaml diff --git a/docs/.sphinx/.pymarkdown.json b/docs/_dev/.pymarkdown.json similarity index 100% rename from docs/.sphinx/.pymarkdown.json rename to docs/_dev/.pymarkdown.json diff --git a/docs/.sphinx/get_vale_conf.py b/docs/_dev/get_vale_conf.py similarity index 84% rename from docs/.sphinx/get_vale_conf.py rename to docs/_dev/get_vale_conf.py index 13e7966..015c5ee 100755 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/_dev/get_vale_conf.py @@ -1,21 +1,21 @@ #! /usr/bin/env python +import argparse +import logging import os import shutil import subprocess -import tempfile import sys -import logging -import argparse +import tempfile # Configure logging logging.basicConfig( level=logging.INFO, - format='%(asctime)s - %(levelname)s - %(message)s', - datefmt='%Y-%m-%d %H:%M:%S' + format="%(asctime)s - %(levelname)s - %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", ) -SPHINX_DIR = os.path.join(os.getcwd(), ".sphinx") +DEV_DIR = os.path.join(os.getcwd(), "_dev") GITHUB_REPO = "canonical/documentation-style-guide" GITHUB_CLONE_URL = f"https://github.com/{GITHUB_REPO}.git" @@ -25,9 +25,10 @@ "styles/Canonical", "styles/config/vocabularies/Canonical", "styles/config/dictionaries", - "vale.ini" + "vale.ini", ] + def clone_repo_and_copy_paths(file_source_dest, overwrite=False): """ Clone the repository to a temporary directory and copy required files @@ -47,16 +48,13 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): # Create temporary directory on disk for cloning temp_dir = tempfile.mkdtemp() - logging.info("Cloning repository <%s> to temporary directory: %s", GITHUB_REPO, temp_dir) + logging.info( + "Cloning repository <%s> to temporary directory: %s", GITHUB_REPO, temp_dir + ) clone_cmd = ["git", "clone", "--depth", "1", GITHUB_CLONE_URL, temp_dir] try: - result = subprocess.run( - clone_cmd, - capture_output=True, - text=True, - check=True - ) + result = subprocess.run(clone_cmd, capture_output=True, text=True, check=True) logging.debug("Git clone output: %s", result.stdout) except subprocess.CalledProcessError as e: logging.error("Git clone failed: %s", e.stderr) @@ -82,6 +80,7 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): return is_copy_success + def copy_files_to_path(source_path, dest_path, overwrite=False): """ Copy a file or directory from source to destination @@ -109,9 +108,11 @@ def copy_files_to_path(source_path, dest_path, overwrite=False): else: os.remove(dest_path) else: - logging.info(" Destination exists, skip copying (use overwrite=True to replace): %s", - dest_path) - return True # Skip copying + logging.info( + " Destination exists, skip copying (use overwrite=True to replace): %s", + dest_path, + ) + return True # Skip copying # Copy the source to destination try: @@ -126,14 +127,18 @@ def copy_files_to_path(source_path, dest_path, overwrite=False): logging.error("Copy failed: %s", e) return False + def parse_arguments(): parser = argparse.ArgumentParser(description="Download Vale configuration files") - parser.add_argument("--no-overwrite", action="store_true", help="Don't overwrite existing files") + parser.add_argument( + "--no-overwrite", action="store_true", help="Don't overwrite existing files" + ) return parser.parse_args() + def main(): # Define local directory paths - vale_files_dict = {file: os.path.join(SPHINX_DIR, file) for file in VALE_FILE_LIST} + vale_files_dict = {file: os.path.join(DEV_DIR, file) for file in VALE_FILE_LIST} # Parse command line arguments, default to overwrite_enabled = True overwrite_enabled = not parse_arguments().no_overwrite diff --git a/docs/.sphinx/pa11y.json b/docs/_dev/pa11y.json similarity index 100% rename from docs/.sphinx/pa11y.json rename to docs/_dev/pa11y.json diff --git a/docs/.sphinx/update_sp.py b/docs/_dev/update_sp.py similarity index 87% rename from docs/.sphinx/update_sp.py rename to docs/_dev/update_sp.py index a9259d0..b07923a 100755 --- a/docs/.sphinx/update_sp.py +++ b/docs/_dev/update_sp.py @@ -1,30 +1,31 @@ #! /usr/bin/env python -# Initial update script for the starter pack. +# Initial update script for the Sphinx Stack. # # Requires some manual intervention, but makes identifying updates and differences easier. # # For debugging, please run this script with DEBUGGING=1 -# e.g. user@device:~/git/Canonical/sphinx-docs-starter-pack/docs$ DEBUGGING=1 python .sphinx/update_sp.py +# e.g. user@device:~/git/Canonical/sphinx-stack/docs$ DEBUGGING=1 python _dev/update_sp.py import glob import logging import os -import requests import re import subprocess import sys -from requests.exceptions import RequestException + +import requests from packaging.version import parse as parse_version +from requests.exceptions import RequestException SPHINX_DIR = os.path.abspath(os.path.dirname(__file__)) -DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, '..')) +DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, "..")) REQUIREMENTS = os.path.join(DOCS_DIR, "requirements.txt") SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update") -GITHUB_REPO = "canonical/sphinx-docs-starter-pack" +GITHUB_REPO = "canonical/sphinx-stack" GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}" -GITHUB_API_SPHINX_DIR = f"{GITHUB_API_BASE}/contents/docs/.sphinx" +GITHUB_API_SPHINX_DIR = f"{GITHUB_API_BASE}/contents/docs/_dev" GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main" TIMEOUT = 10 # seconds @@ -43,7 +44,7 @@ def main(): except FileNotFoundError: print("WARNING\nWARNING\nWARNING") print( - "You need to update to at least version 1.0.0 of the starter pack to start using the update function." + "You need to update to at least version 1.0.0 of the Sphinx Stack to start using the update function." ) print("You may experience issues using this functionality.") logging.debug("No local version found. Setting version to None") @@ -61,15 +62,15 @@ def main(): logging.debug("Comparing versions") if parse_version(local_version) < parse_version(latest_release): logging.debug("Local version is older than the release version.") - print("Starter pack is out of date.\n") + print("Sphinx Stack is out of date.\n") - # Identify and download '.sphinx' dir files to '.sphinx/update' + # Identify and download '_dev' dir files to '_dev/update' files_updated, new_files = update_static_files() - # Write new version to file to '.sphinx/update' + # Write new version to file to '_dev/update' download_file( - GITHUB_RAW_BASE + "/docs/.sphinx/version", + GITHUB_RAW_BASE + "/docs/_dev/version", os.path.join(SPHINX_UPDATE_DIR, "version"), ) @@ -84,8 +85,8 @@ def main(): if files_updated: logging.debug("Updated files found and downloaded") print("Differences have been identified in static files.") - print("Updated files have been downloaded to '.sphinx/update'.") - print("Validate and move these files into your '.sphinx/' directory.") + print("Updated files have been downloaded to '_dev/update'.") + print("Validate and move these files into your '_dev/' directory.") else: logging.debug("No files found to update") # Provide information on NEW files @@ -94,7 +95,7 @@ def main(): print( "NOTE: New files have been downloaded\n", "See 'NEWFILES.txt' for all downloaded files\n", - "Validate and merge these files into your '.sphinx/' directory", + "Validate and merge these files into your '_dev/' directory", ) else: logging.debug("No new files found to download") @@ -130,19 +131,19 @@ def main(): except FileNotFoundError: print("requirements.txt not found") print( - "The updated starter pack has moved requirements.txt out of the '.sphinx' dir" + "The updated Sphinx Stack has moved requirements.txt out of the '_dev' dir" ) print("requirements.txt not checked, please update your requirements manually") def update_static_files(): - """Checks local files against remote for new and different files, downloads to '.sphinx/updates'""" + """Checks local files against remote for new and different files, downloads to '_dev/updates'""" files, paths = get_local_files_and_paths() new_file_list = [] for item in query_api(GITHUB_API_SPHINX_DIR).json(): logging.debug(f"Checking {item['name']}") - # Checks existing files in '.sphinx' starter pack static root for changed SHA + # Checks existing files in '_dev' Sphinx Stack static root for changed SHA if item["name"] in files and item["type"] == "file": index = files.index(item["name"]) if item["sha"] != get_git_revision_hash(paths[index]): @@ -154,12 +155,12 @@ def update_static_files(): # Indicate update script needs to be updated and re-run print("WARNING") print( - "THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '.sphinx/updates'." + "THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '_dev/updates'." ) print("WARNING\n") else: logging.debug("File hashes are equal") - # Checks nested files '.sphinx/**/**.*' for changed SHA (single level of depth) + # Checks nested files '_dev/**/**.*' for changed SHA (single level of depth) elif item["type"] == "dir": logging.debug(item["name"] + " is a directory") for nested_item in query_api( @@ -189,7 +190,7 @@ def update_static_files(): SPHINX_UPDATE_DIR, item["name"], nested_item["name"] ), ) - # Downloads NEW files in '.sphinx' starter pack static root + # Downloads NEW files in '_dev' Sphinx Stack static root else: if item["type"] == "file": logging.debug(f"No local version found of {item['name']}") @@ -225,7 +226,7 @@ def get_git_revision_hash(file) -> str: # Examines local files def get_local_files_and_paths(): - """Identify '.sphinx' local files and paths""" + """Identify '_dev' local files and paths""" logging.debug("Checking local files and paths") try: files = [] diff --git a/docs/_dev/version b/docs/_dev/version new file mode 100644 index 0000000..cd5ac03 --- /dev/null +++ b/docs/_dev/version @@ -0,0 +1 @@ +2.0 diff --git a/docs/_dev/warnings.txt b/docs/_dev/warnings.txt new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html index f4ccfe0..e1d1088 100644 --- a/docs/_templates/footer.html +++ b/docs/_templates/footer.html @@ -41,15 +41,26 @@
{%- if hasdoc('copyright') %} {% trans path=pathto('copyright'), copyright=copyright|e -%} - Copyright © {{ copyright }} + © {{ copyright }} {{ author }} {%- endtrans %} {%- else %} {% trans copyright=copyright|e -%} - Copyright © {{ copyright }} + © {{ copyright }} {{ author }} {%- endtrans %} {%- endif %}
{%- endif %} + {%- if license and license.name -%} + {%- if license.url -%} +
+ This page is licensed under {{ license.name }} +
+ {%- else -%} +
+ This page is licensed under {{ license.name }} +
+ {%- endif -%} + {%- endif -%} {# mod: removed "Made with" #} diff --git a/docs/conf.py b/docs/conf.py index 22dc620..844182f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,7 @@ import datetime import os +import textwrap + import yaml # Configuration for the Sphinx documentation builder. @@ -11,147 +13,63 @@ # A complete list of built-in Sphinx configuration values: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -# Our Starter Pack uses the custom Canonical Sphinx extension -# to keep all documentation based on it consistent and on brand: +# The Sphinx Stack uses the Canonical Sphinx theme to keep all documentation consistent +# and on brand: # https://github.com/canonical/canonical-sphinx - ####################### # Project information # ####################### # Project name -# -# TODO: Update with the official name of your project or product +project = "Sphinx Stack" -project = "Documentation Starter Pack" +# Author name; used in the default copyright statement in the page footer author = "Canonical Ltd." -# The year in the copyright statement defaults to the current year, so -# individual document versions show when they were built. -# TODO: If the date must be a range, like in a software license, replace -# 2026 with the starting year of development and use: -# -# copyright = f"2026-{datetime.date.today().year}" - +# The year in the copyright statement copyright = f"{datetime.date.today().year}" -# Sidebar documentation title; best kept reasonably short -# -# TODO: To include a version number, add it here (hardcoded or automated). -# -# TODO: To disable the title, set to an empty string. - +# Sidebar documentation title +# To disable the title, set it to an empty string. html_title = project + " documentation" - # Documentation website URL -# -# TODO: Update with the official URL of your docs or leave empty if unsure. -# -# NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph -# and is used by social media platforms; see https://ogp.me/ - -ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/" - +ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # Preview name of the documentation website -# -# TODO: To use a different name for the project in previews, update as needed. - ogp_site_name = project - # Preview image URL -# -# TODO: To customise the preview image, update as needed. - ogp_image = "https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg" - -# Product favicon; shown in bookmarks, browser tabs, etc. - -# TODO: To customise the favicon, uncomment and update as needed. - -# html_favicon = '.sphinx/_static/favicon.png' - - # Dictionary of values to pass into the Sphinx context for all pages: # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context html_context = { # Product page URL; can be different from product docs URL - # - # TODO: Change to your product website URL, - # dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'. - # - # TODO: If there's no such website, - # remove the {{ product_page }} link from the page header template - # (usually .sphinx/_templates/header.html; also, see README.rst). "product_page": "documentation.ubuntu.com", - # Product tag image; the orange part of your logo, shown in the page header - # - # TODO: To add a tag image, uncomment and update as needed. - # 'product_tag': '_static/tag.png', # Your Discourse instance URL - # - # TODO: Change to your Discourse instance URL or leave empty. - # - # NOTE: If set, adding ':discourse: 123' to an .rst file - # will add a link to Discourse topic 123 at the bottom of the page. "discourse": "https://discourse.ubuntu.com", # Your Mattermost channel URL - # - # TODO: Change to your Mattermost channel URL or leave empty. "mattermost": "https://chat.canonical.com/canonical/channels/documentation", # Your Matrix channel URL - # - # TODO: Change to your Matrix channel URL or leave empty. "matrix": "https://matrix.to/#/#documentation:ubuntu.com", # Your documentation GitHub repository URL - # - # TODO: Change to your documentation GitHub repository URL or leave empty. - # - # NOTE: If set, links for viewing the documentation source files - # and creating GitHub issues are added at the bottom of each page. - "github_url": "https://github.com/canonical/sphinx-docs-starter-pack", + "github_url": "https://github.com/canonical/sphinx-stack", # Docs branch in the repo; used in links for viewing the source files - # - # TODO: To customise the branch, uncomment and update as needed. - 'repo_default_branch': 'main', + "repo_default_branch": "main", # Docs location in the repo; used in links for viewing the source files - # - - - # TODO: To customise the directory, uncomment and update as needed. "repo_folder": "/docs/", - # TODO: To enable or disable the Previous / Next buttons at the bottom of pages - # Valid options: none, prev, next, both - # "sequential_nav": "both", - # TODO: To enable listing contributors on individual pages, set to True "display_contributors": False, - - # Required for feedback button - 'github_issues': 'enabled', - + # Required for feedback button + "github_issues": "enabled", # Inherit the author value "author": author, - - # The Starter Pack uses CC-BY-SA as the license - # - # TODO: If your docs need another license, specify it instead of 'CC-BY-SA'. - # For the name, we recommend using the standard shorthand identifier from - # https://spdx.org/licenses - # - # For the URL, link directly to the license statement, typically found on - # the product's home page or in its GitHub project. - # - # TODO: If your documentation is a part of the code repository of your project, - # it inherits the code license instead; specify it instead of 'CC-BY-SA'. - + # The Sphinx Stack uses CC-BY-SA as the license "license": { "name": "CC-BY-SA-3.0", - "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE", + "url": "https://github.com/canonical/sphinx-stack-docs/blob/main/LICENSE", }, } @@ -162,51 +80,26 @@ tags.add("openapi") html_extra_path.append("how-to/assets/openapi.yaml") -# TODO: To enable the edit button on pages, uncomment and change the link to a -# public repository on GitHub or Launchpad. Any of the following link domains -# are accepted: -# - https://github.com/example-org/example" -# - https://launchpad.net/example -# - https://git.launchpad.net/example -# -# html_theme_options = { -# 'source_edit_link': 'https://github.com/canonical/sphinx-docs-starter-pack', -# } - -# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 -# -# TODO: If your documentation is hosted on https://docs.ubuntu.com/, -# uncomment and update as needed. - -# slug = '' - ####################### # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/ ####################### # Use RTD canonical URL to ensure duplicate pages have a specific canonical URL - html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # sphinx-sitemap uses html_baseurl to generate the full URL for each page: - -sitemap_url_scheme = '{link}' +sitemap_url_scheme = "{link}" # Include `lastmod` dates in the sitemap: - sitemap_show_lastmod = True # Exclude generated pages from the sitemap: - sitemap_excludes = [ - '404/', - 'genindex/', - 'search/', + "404/", + "genindex/", + "search/", ] -# TODO: Add more pages to sitemap_excludes if needed. Wildcards are supported. -# For example, to exclude module pages generated by autodoc, add '_modules/*'. - ################################ # Template and asset locations # ################################ @@ -231,14 +124,28 @@ rediraffe_dir_only = True +############################ +# sphinx-llm configuration # +############################ + +# This description is included in llms.txt to provide some initial context for your +# product docs. +llms_txt_description = textwrap.dedent( + """\ + This is the documentation for the Sphinx Stack, a template repository + that helps you set up, build, and publish Sphinx documentation. + """ +) + +# The base URL for references built by sphinx-markdown-builder. +if os.environ.get("READTHEDOCS"): + markdown_http_base = html_baseurl + ########################### # Link checker exceptions # ########################### # A regex list of URLs that are ignored by 'make linkcheck' -# -# TODO: Remove or adjust the ACME entry after you update the contributing guide - linkcheck_ignore = [ "http://127.0.0.1:8000", "https://github.com", @@ -246,35 +153,21 @@ "https://example.com", # SourceForge domains often block linkcheck r"https://.*\.sourceforge\.(net|io)/.*", - ] +] # A regex list of URLs where anchors are ignored by 'make linkcheck' - linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] -# give linkcheck multiple tries on failure -# linkcheck_timeout = 30 +# Give linkcheck multiple tries on failure linkcheck_retries = 3 ######################## # Configuration extras # ######################## -# Custom MyST syntax extensions; see -# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -# -# NOTE: By default, the following MyST extensions are enabled: -# substitution, deflist, linkify - -# myst_enable_extensions = set() - - # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html - -# NOTE: The canonical_sphinx extension is required for the Starter Pack. - extensions = [ "canonical_sphinx", "notfound.extension", @@ -287,6 +180,7 @@ "sphinx_config_options", "sphinx_contributor_listing", "sphinx_filtered_toctree", + "sphinx_llm.txt", "sphinx_related_links", "sphinx_roles", "sphinx_terminal", @@ -299,57 +193,34 @@ ] # Excludes files or directories from processing - exclude_patterns = [ "doc-cheat-sheet*", ".venv*", ] -# Adds custom CSS files, located under 'html_static_path' - +# Adds custom CSS files, located remotely or in 'html_static_path' # html_css_files = [ # "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", # ] - -# Adds custom JavaScript files, located under 'html_static_path' - +# Adds custom JavaScript files, located remotely or in 'html_static_path' # html_js_files = [ # "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", # ] - # Specifies a reST snippet to be appended to each .rst file - rst_epilog = """ -.. include:: /reuse/links.txt -.. include:: /reuse/substitutions.txt +.. |RST| replace:: :abbr:`reST (reStructuredText)` +.. |version_number| replace:: 0.1.0 +.. |rest_text| replace:: *Multi-line* text + that uses basic **markup**. +.. |site_link| replace:: Website link +.. _site_link: https://example.com """ -# Feedback button at the top; enabled by default -# -# TODO: To disable the button, uncomment this. - -# disable_feedback_button = True - - -# Your manpage URL -# -# TODO: To enable manpage links, uncomment and replace {codename} with required -# release, preferably an LTS release (e.g. noble). Do *not* substitute -# {section} or {page}; these will be replaced by sphinx at build time -# -# NOTE: If set, adding ':manpage:' to an .rst file -# adds a link to the corresponding man section at the bottom of the page. - -# manpages_url = 'https://manpages.ubuntu.com/manpages/{codename}/en/' + \ -# 'man{section}/{page}.{section}.html' - - # Specifies a reST snippet to be prepended to each .rst file # This defines a :center: role that centers table cell content. # This defines a :h2: role that styles content for use with PDF generation. - rst_prolog = """ .. role:: center :class: align-center @@ -362,18 +233,26 @@ """ # Workaround for https://github.com/canonical/canonical-sphinx/issues/34 - if "discourse_prefix" not in html_context and "discourse" in html_context: html_context["discourse_prefix"] = f"{html_context['discourse']}/t/" -# Workaround for substitutions.yaml - -if os.path.exists('./reuse/substitutions.yaml'): - with open('./reuse/substitutions.yaml', 'r') as fd: +# If the user has a reuse/substitutions.yaml file, load from there. +# Otherwise, use the manual definitions below. +if os.path.exists("./reuse/substitutions.yaml"): + with open("./reuse/substitutions.yaml", "r") as fd: myst_substitutions = yaml.safe_load(fd.read()) +else: + myst_substitutions = { + "version_number": "0.1.0", + "formatted_text": "*Multi-line* text\n that uses basic **markup**.", + "site_link": "[Website link](https://example.com)", + } # Add configuration for intersphinx mapping # Map only the Sphinx documentation sets that you need to link to from your docs set. intersphinx_mapping = { - 'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None) + "sphinxcontrib-mermaid": ( + "https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest", + None, + ) } diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 3d2e744..780a64b 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: How to test the Ulwazi theme in a documentation project based on Canonical's Sphinx Starter Pack. + description: How to test the Ulwazi theme in a documentation project based on Sphinx Stack. relatedlinks: "[Ulwazi on PyPI](https://pypi.org/project/ulwazi), [Vanilla](https://vanillaframework.org), [sphinx-basic-ng](https://github.com/pradyunsg/sphinx-basic-ng)" --- @@ -9,37 +9,81 @@ relatedlinks: "[Ulwazi on PyPI](https://pypi.org/project/ulwazi), [Vanil # Test the Ulwazi theme -Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionality derived from sphinx-basic-ng. +Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionality +derived from sphinx-basic-ng. -This guide outlines the steps required to use the Ulwazi theme in your Sphinx documentation project. +This guide outlines the steps required to use the Ulwazi theme in your Sphinx +documentation project. + +We recommend creating a new branch of your repository and testing Ulwazi in that branch. +You can build the Ulwazi-themed documentation locally from the branch or open a PR and +view the changes in its RTD preview. ## Update the dependencies -In your project's Python requirements, replace the canonical-sphinx package with Ulwazi and its dependencies. The minimum set is: +In your project's Python requirements (`requirements.txt`), replace the Canonical Sphinx +package with Ulwazi and its dependencies: -```{code-block} text +```{code-block} diff :caption: requirements.txt -sphinx -build -sphinx-autobuild -canonical-sphinx-config @ git+https://github.com/Canonical/canonical-sphinx-config.git@main -myst-parser~=4.0 -sphinx-basic-ng -sphinxcontrib-jquery -beautifulsoup4 -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap -ulwazi +- canonical-sphinx ++ sphinx ++ build ++ sphinx-autobuild ++ canonical-sphinx-config @ git+https://github.com/Canonical/canonical-sphinx-config.git@main ++ myst-parser~=4.0 ++ sphinx-basic-ng ++ sphinxcontrib-jquery ++ beautifulsoup4 ++ packaging ++ sphinxcontrib-svg2pdfconverter[CairoSVG] ++ sphinx-last-updated-by-git ++ sphinx-sitemap ++ sphinx-terminal ++ ulwazi ``` -## Update the configuration +Be ready to add any other missing extensions if you see errors about them. + +## Main configuration + +Updating the project configuration is the most critical step in this process. + +There are two main ways to do that: + +* Simple way -- Adapt the [Sample `conf.py` for + Ulwazi](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) by + adjusting the values for your specific documentation. +* Hard way -- Adapt your existing configuration by adding all required values. -This is the most important and tricky part -- updating the project configuration. A reference `conf.py` with all the required configuration and TODO markers is provided in the Ulwazi repository as [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py). Copy it as the starting point for a new documentation set, or use it as a checklist when migrating an existing one. +We strongly recommend trying the first option (the simple way) first as it proved to be +faster and less troublesome, yet enough for testing the theme. Choose the hard way if +your project already has significant `conf.py` customisation that would be difficult to +recreate from the Sample `conf.py` for Ulwazi. -### Set the theme +### The simple way + +Here is the simple way of trying Ulwazi: + +1. Copy the [Sample `conf.py` for + Ulwazi](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) file + inside your documentation folder. +2. Rename the old `conf.py` to some other name, like `old-conf.py`. +3. Rename the sample configuration file to `conf.py`. +4. Open the old and new files side by side and update relevant values in the new + configuration file for your specific product and documentation. + +### The hard way + +The following instructions describe the modifications needed to support Ulwazi in an +existing `conf.py` file. Use this approach if you want to preserve as much of your +original `conf.py` as possible, for example in a heavily customised deployment or when +troubleshooting a configuration issue. + +For an example of all the changes, see the [Charmed Apache Kafka Ulwazi PR](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). + +#### Set the theme Tell Sphinx to use Ulwazi as the theme: @@ -49,54 +93,53 @@ Tell Sphinx to use Ulwazi as the theme: html_theme = "ulwazi" ``` -### Update the extensions +#### Update the extensions -In the list of extensions, replace canonical-sphinx with Ulwazi, and its dependencies: +In the list of extensions, replace Canonical Sphinx with Ulwazi and its dependencies: ```{code-block} diff :caption: extensions in conf\.py --"canonical-sphinx~=0.6" -+"ulwazi" +-"canonical-sphinx~=0.6", ++"ulwazi", +"sphinx_terminal", +"canonical_sphinx_config", +"myst_parser", +"sphinxcontrib.jquery", ``` -If you need PDF output, add `sphinx_modern_pdf_style` to the list. +If you need **PDF output**, add `sphinx_modern_pdf_style` to the extensions list and `sphinx-modern-pdf-style` to `requirements.txt`. -This is only a partial list. Your project may require additional extensions beyond those listed here. +```{caution} +Your project may require additional extensions beyond those listed here. +``` -### Add the required variables +#### Add the required variables Add and fill the following variables immediately before `html_context = {`: ```python # TODO: Adjust to point to the repository where your documentation source files # are stored. - github_repo = # TODO: Select the default syntax for docs source files. # This is for a fallback view/edit source code buttons. - default_source_extension = ".md" # TODO: Change to your product website URL, # dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'. - product_page = ``` If your project is written in reST, set `default_source_extension` to `".rst"`. -### Update the HTML context +#### Update the HTML context You need to make several updates to the `html_context` dictionary. -For an example of all the changes, see the [Charmed Apache Kafka Ulwazi PR](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). -The code snippets in this section might not match the exact layout of `html_context` in your `conf.py`. +The code snippets in this section might not match the exact layout of `html_context` in +your `conf.py` file. Add these new variables, including the top-level variables you declared earlier: @@ -108,7 +151,7 @@ Add these new variables, including the top-level variables you declared earlier: "license": { "name": "Apache-2.0", # TODO: set your license "url": github_repo + "/blob/main/LICENSE", -} +}, ``` Add these entries so the theme can display the project name and author without duplicating them: @@ -121,7 +164,8 @@ Add these entries so the theme can display the project name and author without d ``` Add these entries to configure the settings related to your GitHub repository. -`default_edit_url` and `default_view_url` serve as fallback URLs for the view/edit source buttons on pages that do not have a specific source file path set. +`default_edit_url` and `default_view_url` serve as fallback URLs for the view/edit +source buttons on pages that do not have a specific source file path set. ```{code-block} python :caption: html_context in conf\.py @@ -146,7 +190,8 @@ Add the horizontal navigation menu configuration: # "link2_name": "Second optional link", ``` -Uncomment and adjust the parameters for `link1` and `link2` if you want to add the links in the top navigation bar. +Uncomment and adjust the parameters for `link1` and `link2` if you want to add the links +in the top navigation bar. Add main logo parameters and adjust their values for your documentation: @@ -180,7 +225,7 @@ Add the following parameters for the footer. } ``` -### Add syntax highlighting +#### Add syntax highlighting Add these syntax highlighting settings after the list of extensions: @@ -191,7 +236,7 @@ highlight_language = "none" # default pygments_style = "autumn" # see https://pygments.org/styles for more ``` -### Configure the sitemap +#### Configure the sitemap Add the lastmod setting to the sitemap section: @@ -201,9 +246,10 @@ Add the lastmod setting to the sitemap section: sitemap_show_lastmod = True ``` -### Configure PDF output +#### Configure PDF output -If you need to render your docs to PDF, add the following at the end of the configuration: +If you need to render your docs to PDF, add the following at the end of the +configuration: ```{code-block} python :caption: conf\.py @@ -211,9 +257,10 @@ If you need to render your docs to PDF, add the following at the end of the conf set_modern_pdf_config = True ``` -### Update the copyright +#### Update the copyright -The Ulwazi theme expects a plain year string rather than the older {spellexception}`CC-BY-SA` format. +The Ulwazi theme expects a plain year string rather than the older +{spellexception}`CC-BY-SA` format. ```{code-block} python :caption: conf\.py @@ -225,7 +272,10 @@ The license information is now conveyed through the "license" key in "html_conte ## Test the documentation -Once configuration is complete, review everything again and build it from scratch (cleaning out the existing build files first): +Once configuration is complete, make sure the required extensions are listed in both the +`extensions` list in `conf.py` and the `requirements.txt` file. + +Build the documentation from scratch by first cleaning out any existing build files: ```shell cd docs @@ -233,6 +283,16 @@ make clean make run ``` -This will start a local server at http://127.0.0.1:8000. Open it in your browser to verify the pages render correctly. +If the build fails, check the build logs to identify the cause. +Common issues are: + +1. Missing extensions +2. Missing required values in `conf.py` + +Fix any issues and rebuild. + +Once the build succeeds, a local server starts at http://127.0.0.1:8000. Open that URL +in your browser to verify that the pages render correctly. -Report issues or feature requests in the [Ulwazi GitHub repository](https://github.com/canonical/ulwazi/issues/new). +Report issues or feature requests in the [Ulwazi GitHub +repository](https://github.com/canonical/ulwazi/issues/new). \ No newline at end of file diff --git a/docs/reuse/components.yaml b/docs/explanation/assets/components.yaml similarity index 89% rename from docs/reuse/components.yaml rename to docs/explanation/assets/components.yaml index d975564..4918b05 100644 --- a/docs/reuse/components.yaml +++ b/docs/explanation/assets/components.yaml @@ -1,3 +1,4 @@ +# This file contains the recipes for the Mermaid diagrams used in components.md documentation_architecture: - diagram_name: "Sphinx" description: "The core process of transforming source files into HTML using Sphinx." @@ -6,7 +7,7 @@ documentation_architecture: A["Source Files
(.rst or .md)"] -->|provides content to| C[Sphinx] B["Configuration
(docs/conf.py)"] -->|provides settings to| C C -->|generates| D[Built HTML Pages] - rendered_image: "../explanation/assets/sphinx.png" + rendered_image: "sphinx.png" - diagram_name: "Python environment" description: "The relationship between the host system and the virtual environment." @@ -23,7 +24,7 @@ documentation_architecture: end Sphinx -->|builds| HTML[HTML] end - rendered_image: "../explanation/assets/python-starter-pack.png" + rendered_image: "python-starter-pack.png" - diagram_name: "Extensions" description: "How built-in and third-party extensions are integrated and activated via requirements and conf.py." @@ -38,7 +39,7 @@ documentation_architecture: end BuiltIn -->|are activated in| Conf[/"Project configuration file (docs/conf.py)"\] ThirdParty -->|are activated in| Conf - rendered_image: "../explanation/assets/extensions.png" + rendered_image: "extensions.png" - diagram_name: "Read the Docs" description: "Details the declaration of build logic in the RTD configuration file for hosting." @@ -49,7 +50,7 @@ documentation_architecture: Python_Ver["Python version"] -->|is declared in| RTD_Conf RTD_Conf -->|defines the build logic for| RTD["Read the Docs (RTD)"] RTD -->|builds and hosts| HTML[/"HTML"\] - rendered_image: "../explanation/assets/rtd-build.png" + rendered_image: "rtd-build.png" - diagram_name: "Third-party extensions" description: "Focuses on the specific installation path for external dependencies via pip and requirements." @@ -64,4 +65,4 @@ documentation_architecture: end Python -->|installs the contents of| Reqs Reqs -->|specifies| ThirdParty - rendered_image: "../explanation/assets/third-party-extensions.png" \ No newline at end of file + rendered_image: "third-party-extensions.png" \ No newline at end of file diff --git a/docs/explanation/assets/python-starter-pack.png b/docs/explanation/assets/python-sphinx-stack.png similarity index 100% rename from docs/explanation/assets/python-starter-pack.png rename to docs/explanation/assets/python-sphinx-stack.png diff --git a/docs/explanation/build.rst b/docs/explanation/build.rst index 1fb8ce7..0652f31 100644 --- a/docs/explanation/build.rst +++ b/docs/explanation/build.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Learn about the function, structure, and design of the build process in Canonical's Starter Pack. + :description: Learn about the function, structure, and design of the build process in the Sphinx Stack. :relatedlinks: [GNU Make](https://www.gnu.org/software/make/) @@ -9,7 +9,7 @@ Build ====== -Canonical's Starter Pack uses Make as its build system. Make was chosen because it's +The Sphinx Stack uses Make as its build system. Make was chosen because it's well-tested and available on all platforms. The majority of the build configuration is defined in ``docs/Makefile``. @@ -22,7 +22,7 @@ different locations without changing the docs ``Makefile``. Being primarily a Python project, all dependencies are stored in a virtual environment, ``docs/.venv`` by default. The environment is ephemeral and subject to frequent change. -Installing the Starter Pack initializes it, while cleaning and updating tears it +Installing the Sphinx Stack initializes it, while cleaning and updating tears it down and rebuilds it. @@ -31,7 +31,7 @@ down and rebuilds it. Parent projects and the build ----------------------------- -The Starter Pack is arranged as a standalone project. When it's used in a larger +The Sphinx Stack is arranged as a standalone project. When it's used in a larger project, the docs are a subsystem among other components. If the parent project uses a build system, Make or otherwise, the doc build exists in @@ -60,17 +60,17 @@ difficulty: or manually calling the docs Makefile with ``make -C docs ``. - Storing multiple virtual environments bloats the host system. It's reasonable for project maintainers to prefer a shared build environment. -- The Starter Pack's update process can make changes to many files in the ``docs`` +- The update process in the Sphinx Stack can make changes to many files in the ``docs`` directory. Updating is potentially much simpler if the parent project modifies only a minimum of files in the directory. - With quality assurance and continuous integration, it's simpler if the project can use the same interface to run local and remote checks. More specifically, the parent build - system and CI need a way to call the Starter Pack's ``links``, ``spelling``, and - ``vale`` checks. + system and CI need a way to call the ``links``, ``spelling``, and ``vale`` checks in + the Sphinx Stack. One possible resolution is for the parent build to manually recreate the docs build, tightly coupling the parent build to the existing docs configuration. But this poses -another challenge, because the docs ``Makefile`` might change during a Starter Pack +another challenge, because the docs ``Makefile`` might change during a Sphinx Stack update, requiring a rewrite of the parent build recipes. The solution to these complications is to create a bridge between the two builds, from diff --git a/docs/explanation/components.rst b/docs/explanation/components.rst index 79b402e..51c8cd6 100644 --- a/docs/explanation/components.rst +++ b/docs/explanation/components.rst @@ -1,12 +1,12 @@ .. meta:: - :description: A breakdown of Canonical's Sphinx Starter Pack that covers its constituent elements and their purpose. + :description: A breakdown of the constituent elements of the Sphinx Stack. .. _explanation-structure: -Starter Pack structure -======================= +Sphinx Stack structure +====================== -The Starter Pack is a template `Sphinx `__ +The Sphinx Stack is a template `Sphinx `__ project. It provides a default file structure, a theme, and dependencies for Canonical documentation. @@ -15,10 +15,10 @@ Sphinx ------ Sphinx is a documentation static site generator that converts reStructuredText or -Markdown files into HTML. It's the core software in the Starter Pack. +Markdown files into HTML. It's the core software in the Sphinx Stack. -``docs/conf.py`` is a configuration file that defines the properties of the Sphinx -project such as project metadata and extensions. +The ``docs/conf.py`` file is a configuration file that defines the properties of the +Sphinx project such as project metadata and extensions. .. figure:: assets/sphinx.png :class: with-border @@ -29,17 +29,18 @@ project such as project metadata and extensions. Python ------ -Because Sphinx is a Python application, the Starter Pack depends on Python and a Python +Because Sphinx is a Python application, the Sphinx Stack depends on Python and a Python package manager. Most of its dependencies are Python packages. Local builds of the -Starter Pack require a Python virtual environment to isolate the project from the host +Sphinx Stack require a Python virtual environment to isolate the project from the host system. -To be able to work on a Starter Pack project, your host needs Python 3.11, pip, and venv. +To be able to work on a Sphinx Stack project, your host needs Python 3.11, pip, and +venv. -.. figure:: assets/python-starter-pack.png +.. figure:: assets/python-sphinx-stack.png :class: with-border - Python's role in the Starter Pack + Python's role in the Sphinx Stack Sphinx extensions @@ -48,7 +49,7 @@ Sphinx extensions The syntax and behavior of Sphinx can be modified with extensions. These can be used to create diagrams, test code, and more. -The Starter Pack includes a curated and tested set of extensions. +The Sphinx Stack includes a curated and tested set of extensions. .. figure:: assets/extensions.png :class: with-border @@ -60,8 +61,8 @@ Built-in extensions ~~~~~~~~~~~~~~~~~~~ Built-in extensions do not need to be installed separately from Sphinx and can be -enabled through the configuration file. The ``conf.py`` file has already been -configured to enabled typical extensions necessary for documentation work. +enabled through the configuration file. The ``conf.py`` file has already been configured +to enabled typical extensions necessary for documentation work. Third-party extensions @@ -70,7 +71,7 @@ Third-party extensions If an extension is not built into Sphinx, you must include it in the ``requirements.txt`` file before enabling it in the Sphinx configuration file. -Extensions are Python packages, and the Starter Pack manages them with a +Extensions are Python packages, and the Sphinx Stack manages them with a `requirements.txt `__ file. @@ -99,7 +100,7 @@ The Canonical theme is packaged as a standalone `canonical-sphinx Command-line tools ------------------ -The Starter Pack uses Make as its local build system. The Starter Pack's Makefile +The Sphinx Stack uses Make as its local build system. The Makefile in the Sphinx Stack provides a command-line interface for setting up the virtual environment, installing dependencies, building the documentation, and more. @@ -125,7 +126,7 @@ Read The Docs is a documentation building and hosting platform. It takes the documentation created using Sphinx (or other tools) and builds and publishes it online. If you are publishing your documentation through Read the Docs, the Read the Docs build -logic is declared in ``.readthedocs.yaml``. The Starter Pack comes with a pre-configured +logic is declared in ``.readthedocs.yaml``. The Sphinx Stack comes with a pre-configured ``.readthedocs.yaml`` with default values that should work for the majority of projects. See :ref:`publish-on-rtd` to learn how configure your Read the Docs instance. diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index e4a1112..10d3db2 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Explore topics about the concepts and ideas in Canonical's Starter Pack. + :description: Explore topics about the concepts and ideas in the Sphinx Stack. .. _explanation: @@ -7,9 +7,9 @@ Explanation =========== -Explore topics about the concepts and ideas in Canonical's Starter Pack. +Explore topics about the concepts and ideas in the Sphinx Stack. -The Starter Pack is built using standard Python tools, and is both deep and flexible. +The Sphinx Stack is built using standard Python tools, and is both deep and flexible. .. toctree:: :maxdepth: 1 diff --git a/docs/explanation/sitemaps.rst b/docs/explanation/sitemaps.rst index d588d2c..0433881 100644 --- a/docs/explanation/sitemaps.rst +++ b/docs/explanation/sitemaps.rst @@ -1,79 +1,84 @@ .. meta:: - :description: An in-depth look at the sitemaps feature in the Starter Pack, including configuration, validation, and versioning. + :description: An in-depth look at the sitemaps feature in the Sphinx Stack, including configuration, validation, and versioning. .. _sitemaps: Sitemaps -========= +======== -The latest version of the Starter Pack generates a sitemap for your documentation +The latest version of the Sphinx Stack generates a sitemap for your documentation using the `sphinx-sitemap `_ extension. -This page goes over the nuances of configuring sitemaps, as well as how the -extension must be configured in your Starter Pack project. +This page goes over the nuances of configuring sitemaps, as well as how the extension +must be configured in your Sphinx Stack project. + Read the Docs-generated sitemaps --------------------------------- -RTD generates a basic sitemap pointing to the index page, and relies on -crawlers to index the site. This is sufficient for some projects, but RTD -does not generate sitemaps for subprojects. +RTD generates a basic sitemap pointing to the index page, and relies on crawlers to +index the site. This is sufficient for some projects, but RTD does not generate sitemaps +for subprojects. + +This means any project under the Ubuntu documentation library project must generate its +own sitemap. -This means any project under the Ubuntu documentation library project must -generate its own sitemap. ``sphinx-sitemap``-generated sitemaps -------------------------------------- -The standard Starter Pack uses the ``dirhtml`` builder for Sphinx recipes in the +The standard Sphinx Stack uses the ``dirhtml`` builder for Sphinx recipes in the project's Makefile. -If your project uses an older version of the Starter Pack or -changes the builder, the links generated by the sitemap will be malformed. Either -:ref:`update to the latest version of the Starter Pack ` or -ensure your project's recipes use the ``dirhtml`` builder, not ``html``. +If your project uses an older version of the Sphinx Stack or changes the builder, the +links generated by the sitemap will be malformed. Either :ref:`update to the latest +version of the Sphinx Stack ` or ensure your project's recipes use +the ``dirhtml`` builder, not ``html``. Ensure ``sphinx-sitemap`` has been added to your ``docs/requirements.txt`` file. -Add ``sphinx_sitemap`` to ``extensions`` in your configuration file (:file:`docs/conf.py`): +Add ``sphinx_sitemap`` to ``extensions`` in your configuration file (``docs/conf.py``): .. code-block:: extensions = ['sphinx_sitemap'] + Sitemap configuration ^^^^^^^^^^^^^^^^^^^^^ -The Starter Pack's configuration file (:file:`docs/conf.py`) includes default sitemap configuration. +The build configuration file (``docs/conf.py``) in the Sphinx Stack includes default +sitemap configuration. The ``sphinx-sitemap`` extension requires a ``html_baseurl`` variable to be configured. -This is set by default as follows: +By default, this is set as: .. code-block:: python html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") -When building on Read the Docs, this sets ``html_baseurl`` dynamically to the value of the -``READTHEDOCS_CANONICAL_URL`` environment variable, which resolves to the full URL of the documentation -including the version and language (if applicable). +When building on Read the Docs, this sets ``html_baseurl`` dynamically to the value of +the ``READTHEDOCS_CANONICAL_URL`` environment variable, which resolves to the full URL +of the documentation including the version and language (if applicable). In local builds and builds on other hosts, ``html_baseurl`` defaults to ``/``. -The ``sitemap_url_scheme`` variable is set to ``'{link}'`` by default. This uses the value of ``html_baseurl`` to generate -the full URL for each page for the sitemap. +The ``sitemap_url_scheme`` variable is set to ``'{link}'`` by default. This uses the +value of ``html_baseurl`` to generate the full URL for each page for the sitemap. .. note:: - If you are implementing a sitemap on an RTD instance that is not a subproject, - and it uses ``{link}`` for the ``sitemap_url_scheme``, RTD will replace your - sitemap with their own. + If you are implementing a sitemap on an RTD instance that is not a subproject, and + it uses ``{link}`` for the ``sitemap_url_scheme``, RTD will replace your sitemap + with their own. - This is a known bug. The only current workaround is to use a different - `sitemap name `_ + This is a known bug. The only current workaround is to use a different `sitemap name + `_ and a custom ``robots.txt`` pointing to it. + ``lastmod`` configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -82,10 +87,13 @@ Make sure that your configuration file has:: sitemap_show_lastmod = True + Exclude pages ------------- -Pages can be excluded from the sitemap by adding them to `sitemap_excludes` in :file:`docs/conf.py`:: +Pages can be excluded from the sitemap by adding them to `sitemap_excludes` in ``docs/conf.py``: + +.. code-block:: python sitemap_excludes = [ '404/', @@ -93,31 +101,37 @@ Pages can be excluded from the sitemap by adding them to `sitemap_excludes` in : 'search/', ] -Wildcards are supported. For example, ``_modules/*`` excludes the path ``_modules/`` and all paths such as ``_modules/foo/bar/``. For details, see `Excluding Pages `_. +Wildcards are supported. For example, ``_modules/*`` excludes the path ``_modules/`` and +all paths such as ``_modules/foo/bar/``. For details, see `Excluding Pages +`_. + Validate your sitemap --------------------- -A sitemap will be available at different locations, depending on how it is -generated. +A sitemap will be available at different locations, depending on how it is generated. -Read the Docs generated sitemaps are available at the base domain of a project, -while sitemaps generated with this extension will be placed in the base of the URL -schema used. +Read the Docs generated sitemaps are available at the base domain of a project, while +sitemaps generated with this extension will be placed in the base of the URL schema +used. -For example, two sitemaps are generated for the Sphinx sitemap's documentation -as it is hosted on RTD: +For example, two sitemaps are generated for the Sphinx sitemap's documentation as it is +hosted on RTD: -* The first is generated by RTD and is available at the root of the domain: https://sphinx-sitemap.readthedocs.io/sitemap.xml -* The second is generated by the `sphinx-sitemap` extension and is available at the base of the URL schema used by the RTD instance: https://sphinx-sitemap.readthedocs.io/en/latest/sitemap.xml +* The first is generated by RTD and is available at the root of the domain: + https://sphinx-sitemap.readthedocs.io/sitemap.xml +* The second is generated by the sphinx-sitemap extension and is available at the base + of the URL schema used by the RTD instance: + https://sphinx-sitemap.readthedocs.io/en/latest/sitemap.xml .. dropdown:: How to specify a sitemap - A `robots.txt` file dictates which sitemap is used to index a website. You - can use a custom `robots.txt` file by creating your own and adding it to - `html_static_path` in your configuration file. An example can be found in the - `Ubuntu documentation library `_ - project. + A ``robots.txt`` file dictates which sitemap is used to index a website. You can use + a custom ``robots.txt`` file by creating your own and adding it to + ``html_static_path`` in your configuration file. An example can be found in the + `Ubuntu documentation library + `_ project. + Support multiple versions ------------------------- @@ -131,7 +145,7 @@ If you want sitemaps for all your documentation's versions, you need to deploy y documentation with LTS releases, as it makes past versions more prominent to search engines. -For this task, we'll use the Starter Pack as an example. Let's assume it has three +For this task, we'll use the Sphinx Stack as an example. Let's assume it has three versions, 1.0, 2.0, and 3.0, and uses the URL schema of ``/``. First, ensure each version of your documentation has a sitemap generated by this @@ -145,16 +159,16 @@ file, and point to the sitemap files of each of your documentation sets: - https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemap.xml + https://canonical-sphinx-stack.readthedocs-hosted.com/stable/sitemap.xml - https://canonical-starter-pack.readthedocs-hosted.com/3.0/sitemap.xml + https://canonical-sphinx-stack.readthedocs-hosted.com/3.0/sitemap.xml - https://canonical-starter-pack.readthedocs-hosted.com/2.0/sitemap.xml + https://canonical-sphinx-stack.readthedocs-hosted.com/2.0/sitemap.xml - https://canonical-starter-pack.readthedocs-hosted.com/1.0/sitemap.xml + https://canonical-sphinx-stack.readthedocs-hosted.com/1.0/sitemap.xml @@ -169,7 +183,7 @@ At the end of ``robots.txt``, point to the future path of ``sitemapindex.xml``: .. code-block:: :caption: robots.txt - Sitemap: https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemapindex.xml + Sitemap: https://canonical-sphinx-stack.readthedocs-hosted.com/stable/sitemapindex.xml Lastly, add both new files to the configuration file: diff --git a/docs/reuse/mermaid.txt b/docs/how-to/assets/mermaid.txt similarity index 96% rename from docs/reuse/mermaid.txt rename to docs/how-to/assets/mermaid.txt index 68ec1b5..4e62dc3 100644 --- a/docs/reuse/mermaid.txt +++ b/docs/how-to/assets/mermaid.txt @@ -90,11 +90,11 @@ mermaid-diagram-sequence-start `````{tab-item} Custom CSS -First, create a Mermaid stylesheet in the {file}`_static` directory and -customize it as needed. For example, {file}`mermaid-sequence.css`. +First, create a Mermaid stylesheet in the `_static` directory and customize it as +needed. For example, `mermaid-sequence.css`. -Then, enable custom stylesheets in {file}`conf.py`. -Uncomment this line so Sphinx can use local stylesheets: +Then, enable custom stylesheets in `conf.py`. Uncomment this line so Sphinx can use +local stylesheets: ```{code-block} py :caption: conf\.py diff --git a/docs/how-to/build-and-preview.rst b/docs/how-to/build-and-preview.rst index 83d68a8..2ee02bf 100644 --- a/docs/how-to/build-and-preview.rst +++ b/docs/how-to/build-and-preview.rst @@ -6,132 +6,184 @@ Build and preview ================= -The Starter Pack provides a :file:`Makefile` that defines :command:`make` commands to build and view the documentation. +The Sphinx Stack provides a ``Makefile`` that defines ``make`` commands to build and +view the documentation. -This guide describes how to set up your environment and use these commands to build and preview the documentation locally. +This guide describes how to set up your environment and use these commands to build and +preview the documentation locally. -For more advanced information, including how to embed your docs build with your project build, see: +For more advanced information, including how to embed your docs build with your project +build, see: - :ref:`build` - :ref:`bridge-project-and-docs-builds` + Install prerequisite software ----------------------------- -The documentation framework that the Starter Pack uses bundles most prerequisites in a Python virtual environment, so you don't need to worry about installing them. -There are only a few packages that you need to install on your host system. +The documentation framework that the Sphinx Stack uses bundles most prerequisites in a +Python virtual environment, so you don't need to worry about installing them. There are +only a few packages that you need to install on your host system. + +Before you start, make sure that you have ``make``, ``python3``, ``python3-venv``, and +``python3-pip`` on your system: + +.. code-block:: bash -Before you start, make sure that you have ``make``, ``python3``, ``python3-venv``, and ``python3-pip`` on your system:: + sudo apt update + sudo apt install make python3 python3-venv python3-pip - sudo apt update - sudo apt install make python3 python3-venv python3-pip Python environment ------------------ -The Python prerequisites from the :file:`docs/requirements.txt` file are automatically installed when you build the documentation. +The Python prerequisites from the ``docs/requirements.txt`` file are automatically +installed when you build the documentation. + +If you want to install them manually, you can run the following command in your +documentation directory: + +.. code-block:: bash -If you want to install them manually, you can run the following command from within your documentation folder:: + make install - make install +This command creates a virtual environment (``.venv/``) and installs dependency +software within it. -This command creates a virtual environment (:file:`.sphinx/venv/`) and installs dependency software within it. +If you want to remove the installed Python packages (for example, to enforce a +re-installation), run the following command in your documentation directory: -If you want to remove the installed Python packages (for example, to enforce a re-installation), run the following command from within your documentation folder:: +.. code-block:: bash - make clean + make clean .. note:: - - By default, the Starter Pack uses the latest compatible version of all tools and does not pin its requirements. - This might change temporarily if there is an incompatibility with a new tool version. - There is therefore no need to use a tool like Renovate to automatically update the requirements. - - If you encounter the error ``locale.Error: unsupported locale setting`` when activating the Python virtual environment, include the environment variable in the command and try again: ``LC_ALL=en_US.UTF-8 make run`` + - By default, the Sphinx Stack uses the latest compatible version of all tools and + does not pin its requirements. This might change temporarily if there is an + incompatibility with a new tool version. There is therefore no need to use a tool + like Renovate to automatically update the requirements. + - If you encounter the error ``locale.Error: unsupported locale setting`` when + activating the Python virtual environment, include the environment variable in the + command and try again: ``LC_ALL=en_US.UTF-8 make run`` .. important:: - Run these commands from within your documentation folder. + + Run these commands in your documentation directory. + .. _build-docs: Build the documentation ----------------------- -To build the documentation, run the following command:: +To build the documentation, run the following command: + +.. code-block:: bash - make html + make html -This command installs the required tools and renders the output to the :file:`_build/` folder in your documentation folder. +This command installs the required tools and renders the output to the ``docs/_build/`` +directory. .. important:: - When you run :command:`make html` again, it updates the documentation for changed files only. - This speeds up the build, but it can cause you to miss warnings or errors that were displayed before. - To force a clean build, see :ref:`build-clean`. + When you run ``make html`` again, it updates the documentation for changed files + only. + + This speeds up the build, but it can cause you to miss warnings or errors that were + displayed before. To force a clean build, see ``build-clean``. + +Make sure that the documentation builds without any warnings (warnings are treated as +errors). -Make sure that the documentation builds without any warnings (warnings are treated as errors). .. _build-clean: Run a clean build ----------------- -To delete all existing output files and build all files again, run the following command:: +To delete all existing output files and build all files again, run the following command: - make clean-doc html +.. code-block:: bash -To delete both the existing output files and the Python environment and build the full documentation again, run the following command:: + make clean-doc && make html + +To delete both the existing output files and the Python environment and build the full +documentation again, run the following command: + +.. code-block:: bash + + make clean && make html - make clean html View the documentation ---------------------- -To view the documentation output, run the following command:: +To view the documentation output, run the following command: - make serve +.. code-block:: bash -This command builds the documentation and serves it on :literalref:`http://127.0.0.1:8000/`. + make serve + +This command builds the documentation and serves it at +:literalref:`http://127.0.0.1:8000/`. Live view --------- -Instead of building the documentation for each change and then serving it, you can run a live preview of the documentation:: +Instead of building the documentation for each change and then serving it, you can run a +live preview of the documentation: + +.. code-block:: bash - make run + make run -This command builds the documentation and serves it on :literalref:`http://127.0.0.1:8000/`. -When you change a documentation file and save it, the documentation will be automatically rebuilt and refreshed in the browser. +This command builds the documentation and serves it at +:literalref:`http://127.0.0.1:8000/`. When you change a documentation file and save it, +the documentation will be automatically rebuilt and refreshed in the browser. -If you need project-specific options for ``sphinx-autobuild`` such as ``--ignore`` or ``--watch``, pass them through ``SPHINX_AUTOBUILD_OPTS``:: +If you need project-specific options for ``sphinx-autobuild`` such as ``--ignore`` or +``--watch``, pass them through ``SPHINX_AUTOBUILD_OPTS``: - make run SPHINX_AUTOBUILD_OPTS="--ignore '**/*.gen.rst' --watch ../data/" +.. code-block:: bash -If you call ``make run`` from a :ref:`parent project's build `, pass the variable explicitly to the sub-Make call to ensure it reaches the docs Makefile:: + make run SPHINX_AUTOBUILD_OPTS="--ignore '**/*.gen.rst' --watch ../data/" - $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" +If you call ``make run`` from a :ref:`parent project's build +`, pass the variable explicitly to the sub-Make call to +ensure it reaches the docs Makefile: + +.. code-block:: bash + + $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" This approach allows command-line overrides to work intuitively from the parent context. .. important:: - The :command:`run` target is very convenient while working on documentation updates. - However, it is quite error-prone because it displays warnings or errors only when they occur. - If you save other files later, you might miss these messages. + The ``run`` target is very convenient while working on documentation updates. + + However, it is quite error-prone because it displays warnings or errors only when + they occur. If you save other files later, you might miss these messages. + + Therefore, you should always run ``make clean`` before finalizing your changes. - Therefore, you should always :ref:`build-clean` before finalising your changes. Build a PDF ----------- Build a PDF locally with the following command: -.. code-block:: none +.. code-block:: bash make pdf -PDF generation requires specific software packages. If these files are not found, a prompt will be presented and the generation will stop. +PDF generation requires specific software packages. If these files are not found, a +prompt will be presented and the generation will stop. Required software packages include: @@ -156,12 +208,16 @@ On Linux, required packages can be installed with: .. note:: - When generating a PDF, the index page is considered a 'foreword' and will not be labelled with a chapter. + When generating a PDF, the index page is considered a 'foreword' and will not be + labelled with a chapter. .. important:: - When generating a PDF, it is important to not use additional headings before a ``toctree``. Documents referenced by the - ``toctree`` will be nested under any provided headings. + When generating a PDF, it is important to not use additional headings before a + ``toctree``. Documents referenced by the ``toctree`` will be nested under any + provided headings. - A ``rubric`` directive can be combined with the ``h2`` class to provide a heading-styled rubric in the HTML output. See the default ``index.rst`` for an example. - Rubric-based headings aren't included as entries in the table of contents or the navigation sidebar. + A ``rubric`` directive can be combined with the ``h2`` class to provide a + heading-styled rubric in the HTML output. See the default ``index.rst`` for an + example. Rubric-based headings aren't included as entries in the table of contents + or the navigation sidebar. diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst index b597afb..3d9a963 100644 --- a/docs/how-to/configure-your-project.rst +++ b/docs/how-to/configure-your-project.rst @@ -6,86 +6,106 @@ Configure your project ====================== -While the Starter Pack provides default configuration values for most settings, you'll need to set project-specific parameters like the project name to ensure the documentation reflects your project accurately. +While the Sphinx Stack provides default configuration values for most settings, you'll +need to set project-specific parameters like the project name to ensure the +documentation reflects your project accurately. .. important:: - After setting up your repository with the Starter Pack, you should track the changes made to the Starter Pack. + After setting up your repository with the Sphinx Stack, you should track the changes + made to the Sphinx Stack. - Changes to the look and feel, as well as common functionality, will be automatically available through updates to the `Canonical Sphinx`_ extension. + Changes to the look and feel, as well as common functionality, will be automatically + available through updates to the `Canonical Sphinx + `__ extension. - Changes to files that are part of the Starter Pack, for example changes made during steps in :ref:`run-documentation-checks`, might require you to manually update your repository with the required files. - See the Starter Pack's `change log`_ for the most relevant (and of course all breaking) changes. + Changes to files that are part of the Sphinx Stack, for example changes made during + steps in :ref:`run-documentation-checks`, might require you to manually update your + repository with the required files. See the Sphinx Stack `changelog + `__ for the + most relevant (and of course all breaking) changes. -Configuration for a Starter Pack based documentation is set in the :file:`docs/conf.py` Sphinx configuration file. +Configuration for a Sphinx Stack based documentation is set in the ``docs/conf.py`` +Sphinx configuration file. -The Starter Pack's default configuration is prepared in a way that makes sense for most projects. -However, you must set some critical parameters that are unique for your project, like the project's name. +The default configuration in the Sphinx Stack is prepared in a way that makes sense for +most projects. However, you must set some critical parameters that are unique for your +project, like the project's name. + +In addition, you can find some optional parameters or add your own configuration +parameters to the file. -In addition, you can find some optional parameters or add your own configuration parameters to the file. Required customisation ---------------------- -You must check and update some of the parameters specific to your project. -Mandatory parameters are commented with the `TODO` keyword. +You must check and update some of the parameters specific to your project. Mandatory +parameters are commented with the ``TODO`` keyword. The following are some highlights of the available configuration parameters. + Update the project information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Edit the :file:`docs/conf.py` file and update the configuration in the ``Project information`` section. -See the comments in the file for more information about each setting. +Edit the ``docs/conf.py`` file and update the configuration in the ``Project +information`` section. See the comments in the file for more information about each +setting. + Open Graph configuration ^^^^^^^^^^^^^^^^^^^^^^^^ -When you post a link to your documentation somewhere (for example, on Mattermost or Discourse), it might be shown with a preview. -This preview is configured through the Open Graph Protocol (:spellexception:`OGP`) configuration. +When you post a link to your documentation somewhere (for example, on Mattermost or +Discourse), it might be shown with a preview. This preview is configured through the +Open Graph Protocol (:vale-ignore:`OGP`) configuration. + +If you don't know yet where your documentation will be hosted, you can leave the URL +empty. If you do, specify the hosting URL. You can leave the defaults for the website +name and the preview image or specify your own. -If you don't know yet where your documentation will be hosted, you can leave the URL empty. -If you do, specify the hosting URL. -You can leave the defaults for the website name and the preview image or specify your own. Optional customisation ---------------------- -The Starter Pack contains several features that you can configure, or turn off if they aren't suitable for your documentation. +The Sphinx Stack contains several features that you can configure or turn off if they +aren't suitable for your documentation. + Modify the template ~~~~~~~~~~~~~~~~~~~ -The default Starter Pack templates provide an initial configuration for your documentation set, including: +The default Sphinx Stack templates provide an initial configuration for your +documentation set, including: -- Header template - The top section of the page that contains your product's tag image and name, a link to your product's page (if available), and a drop-down menu for "More resources". -- Footer template - The bottom section of the page that contains sequential navigation controls, copyright information, licensing details, and other relevant links. +- Header template - The top section of the page that contains your product's tag image + and name, a link to your product's page (if available), and a drop-down menu for "More + resources". +- Footer template - The bottom section of the page that contains sequential navigation + controls, copyright information, licensing details, and other relevant links. -These project settings are configured in :file:`docs/conf.py` and are generally sufficient for most cases. -However, if you have additional requirements -- such as adding links to announcements or videos that are not part of the documentation -- you can override the default templates to customize them as needed. +These are configured in ``docs/conf.py`` and are sufficient for most cases. However, if +you have additional requirements -- such as adding links to announcements or videos that +are not part of the documentation -- you can override the default templates to customize +them as needed. See the :ref:`custom-html-templates` guide for details on how to do so. + Deactivate the feedback button ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the Starter Pack includes a feedback button at the top of each page. -This button redirects users to your GitHub issues page, and populates an issue for them with details of the page they were on when they clicked the button. - -If your project does not use GitHub issues, set the ``github_issues`` variable in the :file:`docs/conf.py` file to an empty value to disable both the feedback button and the issue link in the footer. - -If you want to deactivate the feedback button, but keep the link in the footer, set ``disable_feedback_button`` in the :file:`docs/conf.py` file to ``True``. - -Configure the contributor display -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, the Sphinx Stack includes a feedback button at the top of each page. This +button redirects users to your GitHub issues page, and populates an issue for them with +details of the page they were on when they clicked the button. -By default, the Starter Pack will display a list of contributors at the bottom of each page. -This requires the GitHub URL and folder to be configured. +If your project does not use GitHub issues, set the ``github_issues`` variable in the +``docs/conf.py`` file to an empty value to disable both the feedback button and the +issue link in the footer. -If you want to turn this contributor listing off, you can do so by setting the ``display_contributors`` variable in the :file:`docs/conf.py` file to ``False``. +If you want to deactivate the feedback button, but keep the link in the footer, set +``disable_feedback_button`` in the ``docs/conf.py`` file to ``True``. -To configure that only recent contributors are displayed, you can set the ``display_contributors_since`` variable. -It takes any Linux date format (for example, a full date, or an expression like "3 months"). Add redirects ~~~~~~~~~~~~~ @@ -106,74 +126,95 @@ Destination paths can also be external URLs. "path/to/old/page" "https://example.com/new-page" + Configure included extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Starter Pack includes a set of extensions that are useful for all documentation sets. -Some extensions are :ref:`enabled by default ` within the Starter Pack, but you can customize the selection in the :file:`docs/conf.py` file. +The Sphinx Stack includes a set of extensions that are useful for all documentation +sets. Some extensions are :ref:`enabled by default +` within the Sphinx Stack, but you can customize +the selection in the ``docs/conf.py`` file. -The ``canonical_sphinx`` extension is required for the Starter Pack and provides the Furo-based theme and custom templates. +The canonical-sphinx extension is required for the Sphinx Stack and provides the +Furo-based theme and custom templates. -To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in :file:`docs/conf.py`. +To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in ``docs/conf.py``. .. note:: - If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the :file:`docs/requirements.txt` file. + If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the ``docs/requirements.txt`` file. + Add page-specific configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can override some global configuration for specific pages. -For example, you can configure whether to display Previous/Next buttons at the bottom of pages by setting the ``sequential_nav`` variable in the :file:`docs/conf.py` file. +For example, you can configure whether to display Previous/Next buttons at the bottom of +pages by setting the ``sequential_nav`` variable in the ``docs/conf.py`` file. .. code:: python - html_context = { - ... - "sequential_nav": "both" - } + html_context = { + ... + "sequential_nav": "both" + } -You can then override this default setting for a specific page (for example, to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). +You can then override this default setting for a specific page (for example, to turn off +the Previous/Next buttons by default, but display them in a multi-page tutorial). -To do so, add `file-wide metadata`_ at the top of a page. -See the following examples for how to enable Previous/Next buttons for one page: +To do so, add `file-wide metadata +`__ at the +top of a page. See the following examples for how to enable Previous/Next buttons for +one page: -|RST|:: +|RST|: - :sequential_nav: both +.. code-block:: - [Page contents] + :sequential_nav: both -MyST:: + [Page contents] - --- - sequential_nav: both - --- +MyST: + +.. code-block:: - [Page contents] + --- + sequential_nav: both + --- -Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the :file:`docs/conf.py` file for more information. + [Page contents] + +Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and +``both``. See the ``docs/conf.py`` file for more information. + +Another example for page-specific configuration is the ``hide-toc`` field (provided by +`Furo `__), which can be used to hide the +page-internal table of content. See `Hiding Contents sidebar +`__. -Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. -See `Hiding Contents sidebar`_. Add your own configuration -------------------------- -Custom configuration parameters for your project can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file. +Custom configuration parameters for your project can be used to extend or override the +common configuration, or to define additional configuration that is not covered by the +common ``conf.py`` file. The following links can help you with additional configuration: -- `Sphinx configuration`_ -- `Sphinx extensions`_ -- `Furo documentation`_ (Furo is the Sphinx theme we use as our base) +- `Sphinx configuration `__ +- `Sphinx extensions `__ +- `Furo documentation `__ + +If you need additional Python packages for any custom processing you do in your +documentation, add them to the ``docs/requirements.txt`` file. -If you need additional Python packages for any custom processing you do in your documentation, add them to the :file:`docs/requirements.txt` file. Disable failure on warning -------------------------- -The docs build (``make html``) is, by default, set to fail when a warning (``WARNING`` in the build log) is encountered. To disable this setting, remove the ``--failure-on-warning`` option from the command specified in the ``html`` target in the ``Makefile``. - +The docs build is, by default, set to fail when a warning (``WARNING`` in the build log) +is encountered. To disable this setting, remove the ``--failure-on-warning`` option from +the command specified in the ``html`` target in the ``Makefile``. diff --git a/docs/how-to/contributing-myst.md b/docs/how-to/contributing-myst.md deleted file mode 100644 index f870722..0000000 --- a/docs/how-to/contributing-myst.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -orphan: true ---- - - - - -# How to contribute - -We believe that everyone has something valuable to contribute, whether you're a coder, a writer, or a tester. Here's how and why you can get involved: - -- **Why join us?** Work with like-minded people, develop your skills, connect with diverse professionals, and make a difference. -- **What do you get?** Personal growth, recognition for your contributions, early access to new features, and the joy of seeing your work appreciated. -- **Start early, start easy**: Dive into code contributions, improve documentation, or be among the first testers. Your presence matters, regardless of experience or the size of your contribution. - -The guidelines below will help keep your contributions effective and meaningful. - -## Code of conduct - -When contributing, you must abide by the [Ubuntu Code of Conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct). - -## Licence and copyright - - - -By default, all contributions to ACME are made under the AGPLv3 licence. See the [licence](https://github.com/canonical/ACME/blob/main/COPYING) in the ACME GitHub repository for details. - -All contributors must sign the [Canonical contributor licence agreement](https://canonical.com/legal/contributors), which grants Canonical permission to use the contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs). - -## Releases and versions - - - -ACME uses [semantic versioning](https://semver.org/); major releases occur once or twice a year. - -The release notes can be found [TODO: here](https://example.com). - -## Environment setup - - - -To work on the project, you need the following prerequisites: - -- [TODO: Prerequisite 1](http://example.com) -- [TODO: Prerequisite 2](http://example.com) - -To install and configure these tools: - -```bash -TODO: prerequisite command 1 -TODO: prerequisite command 2 -``` - -## Submissions - - - -If you want to address an issue or a bug in ACME, notify in advance the people involved to avoid confusion; also, reference the issue or bug number when you submit the changes. - -- Fork [our GitHub repository](https://github.com/canonical/ACME) and add the changes to your fork, properly structuring your commits, providing detailed commit messages, and signing your commits. - -- Make sure the updated project builds and runs without warnings or errors; this includes linting, documentation, code, and tests. - -- Submit the changes as a [pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -Your changes will be reviewed in due time; if approved, they will eventually be merged. - -### Describing pull requests - - - -To be properly considered, reviewed, and merged, your pull request must provide the following details: - -- **Title**: Summarise the change in a short, descriptive title. -- **Description**: Explain the problem that your pull request solves. Mention any new features, bug fixes, or refactoring. -- **Relevant issues**: Reference any [related issues, pull requests, and repositories](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls). -- **Testing**: Explain whether new or updated tests are included. -- **Reversibility**: If you propose decisions that may be costly to reverse, list the reasons and suggest steps to reverse the changes if necessary. - -### Commit structure and messages - - - -Use separate commits for each logical change, and for changes to different components. Prefix your commit messages with the names of components they affect, using the code tree structure. For example, start a commit that updates the ACME service with `ACME/service:`. - -Use [conventional commits](https://www.conventionalcommits.org/) to ensure consistency across the project: - -```none -Ensure correct permissions and ownership for the content mounts - -* Work around an ACME issue regarding empty dirs: https://github.com/canonical/ACME/issues/12345 - -* Ensure the source directory is owned by the user running a container. - -Links: -- ... -- ... -``` - -Such structure makes it easier to review contributions and simplifies porting fixes to other branches. - -### Signing commits - - - -To improve contribution tracking, we use the developer certificate of origin -([DCO 1.1](https://developercertificate.org/) and require signed commits (using -the `-S` or `---gpg-sign` option) for all changes that go into the ACME project. - -```{code-block} none -git commit -S -m "acme/component: updated life cycle diagram" -``` - -Signed commits will have a GPG, SSH, or S/MIME signature that is -cryptographically verifiable, and will be marked with a "Verified" or -"Partially verified" badge in GitHub. This verifies that you made the changes or -have the right to commit it as an open-source contribution. - -To set up locally signed commits and tags, see [GitHub Docs - About commit -signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -````{tip} -You can configure your Git client to sign commits by default for any local -repository by running: - -```{code-block} none -git config --global commit.gpgsign true -``` - -Once you have configured this, you no longer need to add ``-S`` to your -commits explicitly. - -See [GitHub Docs - Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) for more information. -```` - -If you've made an unsigned commit and encounter the "Commits must have verified -signatures" error when pushing your changes to the remote: - -1. Amend the most recent commit by signing it without changing the commit -message, and push again: - - ```{code-block} none - git commit --amend --no-edit -n -S - git push - ``` - -1. If you still encounter the same error, confirm that your GitHub account has -been set up properly to sign commits as described in the [GitHub Docs - About -commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). - ```{tip} - If you use SSH keys to sign your commits, make sure to add a "Signing Key" - type in your GitHub account. See - [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) - for more information. - ``` - -## Code - -### Formatting and linting - - - -ACME relies on these formatting and linting tools: - -- [TODO: Tool 1](http://example.com) -- [TODO: Tool 2](http://example.com) - -To configure and run them: - -```bash -TODO: lint command 1 -TODO: lint command 2 -``` - -### Structure - -- **Check linked code elements**: Ensure coupled code elements, files, and directories are adjacent. For instance, store test data close to the corresponding test code. -- **Group variable declaration and initialisation**: Declare and initialise variables together to improve code organisation and readability. -- **Split large expressions**: Break down large expressions into smaller self-explanatory parts. Use multiple variables where appropriate to make the code more understandable and choose names that reflect their purpose. -- **Use blank lines for logical separation**: Insert a blank line between two logically separate sections of code to improve its structure and readability. -- **Avoid nested conditions**: Avoid nesting conditions to improve readability and maintainability. -- **Remove dead code and redundant comments**: Drop unused or obsolete code and comments to promote a cleaner code base and reduce confusion. -- **Normalise symmetries**: Treat identical operations consistently, using a uniform approach to improve consistency and readability. - -### Best practices - - - -## Tests - - - -All code contributions must include tests. - -To run the tests locally before submitting your changes: - -```bash -TODO: test command 1 -TODO: test command 2 -``` - -## Documentation - -ACME's documentation is stored in the `DOCDIR` directory of the repository. It is based on the [Canonical Starter Pack](https://canonical-starter-pack.readthedocs-hosted.com/stable/) and hosted on [Read the Docs](https://about.readthedocs.com/). - -For general guidance, refer to the [Starter Pack guide](https://canonical-starter-pack.readthedocs-hosted.com/stable/). - -For syntax help and guidelines, refer to the syntax guides contained in the [rST](project:#rst-syntax) and [MyST](project:#myst-syntax) syntax guides. - -In structuring, the documentation employs the [Diátaxis](https://diataxis.fr/) approach. - -To run the documentation locally before submitting your changes: - -```bash -make run -``` - -### Automatic checks - -GitHub runs automatic checks on the documentation to verify spelling, validate links, and suggest inclusive language. - -You can (and should) run the same checks locally: - -```bash -make spelling -make linkcheck -make woke -``` diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst deleted file mode 100644 index cc50b4e..0000000 --- a/docs/how-to/contributing.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. meta:: - :description: How to contribute to the documentation project with code, writing, or testing. - -:orphan: - -.. TODO: Replace all mentions of ACME with your project name -.. TODO: Update all sections containing TODOs; make sure no TODOs are left - - -How to contribute -================= - -We believe that everyone has something valuable to contribute, -whether you're a coder, a writer or a tester. -Here's how and why you can get involved: - -- **Why join us?** Work with like-minded people, develop your skills, - connect with diverse professionals, and make a difference. - -- **What do you get?** Personal growth, recognition for your contributions, - early access to new features and the joy of seeing your work appreciated. - -- **Start early, start easy**: Dive into code contributions, - improve documentation, or be among the first testers. - Your presence matters, - regardless of experience or the size of your contribution. - - -The guidelines below will help keep your contributions effective and meaningful. - - -Code of conduct ---------------- - -When contributing, you must abide by the -`Ubuntu Code of Conduct `_. - - -Licence and copyright ---------------------- - -.. TODO: Update with your license details or drop if excessive - -By default, all contributions to ACME are made under the AGPLv3 licence. -See the `licence `_ -in the ACME GitHub repository for details. - -All contributors must sign the `Canonical contributor licence agreement -`_, -which grants Canonical permission to use the contributions. -The author of a change remains the copyright owner of their code -(no copyright assignment occurs). - - -Releases and versions ---------------------- - -.. TODO: Add your release and versioning details or drop if excessive - -ACME uses `semantic versioning `_; -major releases occur once or twice a year. - -The release notes can be found `TODO: here `_. - - -Environment setup ------------------ - -.. TODO: Update with your prerequisites or drop if excessive - -To work on the project, you need the following prerequisites: - -- `TODO: Prerequisite 1 `_ -- `TODO: Prerequisite 2 `_ - - -To install and configure these tools: - -.. code-block:: console - - TODO: prerequisite command 1 - TODO: prerequisite command 2 - - -Submissions ------------ - -.. TODO: Suggest your own PR process or drop if excessive - -If you want to address an issue or a bug in ACME, -notify in advance the people involved to avoid confusion; -also, reference the issue or bug number when you submit the changes. - -- `Fork - `_ - our `GitHub repository `_ - and add the changes to your fork, - properly structuring your commits, - providing detailed commit messages - and signing your commits. - -- Make sure the updated project builds and runs without warnings or errors; - this includes linting, documentation, code and tests. - -- Submit the changes as a `pull request (PR) - `_. - - -Your changes will be reviewed in due time; -if approved, they will be eventually merged. - - -Describing pull requests -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your own checklist or drop if excessive - -To be properly considered, reviewed and merged, -your pull request must provide the following details: - -- **Title**: Summarise the change in a short, descriptive title. - -- **Description**: Explain the problem that your pull request solves. - Mention any new features, bug fixes or refactoring. - -- **Relevant issues**: Reference any - `related issues, pull requests and repositories `_. - -- **Testing**: Explain whether new or updated tests are included. - -- **Reversibility**: If you propose decisions that may be costly to reverse, - list the reasons and suggest steps to reverse the changes if necessary. - - -Commit structure and messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your own guidelines or drop if excessive - -Use separate commits for each logical change, -and for changes to different components. -Prefix your commit messages with names of components they affect, -using the code tree structure, -e.g. start a commit that updates the ACME service with ``ACME/service:``. - -Use `conventional commits `_ -to ensure consistency across the project: - -.. code-block:: none - - Ensure correct permissions and ownership for the content mounts - - * Work around an ACME issue regarding empty dirs: - https://github.com/canonical/ACME/issues/12345 - - * Ensure the source directory is owned by the user running a container. - - Links: - - ... - - ... - - -Such structure makes it easier to review contributions -and simplifies porting fixes to other branches. - - -Signing commits -~~~~~~~~~~~~~~~ - -.. TODO: Update with your suggestions or drop if excessive - -To improve contribution tracking, we use the developer certificate of origin -(`DCO 1.1 `_) and require signed commits -(using the ``-S`` or ``--gpg-sign`` option) for all changes that go into the -ACME project. - -.. code-block:: none - - git commit -S -m "acme/component: updated life cycle diagram" - -Signed commits will have a GPG, SSH, or S/MIME signature that is -cryptographically verifiable, and will be marked with a "Verified" or -"Partially verified" badge in GitHub. This verifies that you made the changes or -have the right to commit it as an open-source contribution. - -To set up locally signed commits and tags, see `GitHub Docs - About commit -signature verification `_. - -.. tip:: - - You can configure your Git client to sign commits by default for any local - repository by running ``git config --global commit.gpgsign true``. - Once you have configured this, you no longer need to add ``-S`` to your - commits explicitly. - - See `GitHub Docs - Signing commits `_ for more information. - -If you've made an unsigned commit and encounter the "Commits must have verified -signatures" error when pushing your changes to the remote: - -1. Amend the most recent commit by signing it without changing the commit - message, and push again: - - .. code-block:: none - - git commit --amend --no-edit -n -S - git push -#. If you still encounter the same error, confirm that your GitHub account has - been set up properly to sign commits as described in the `GitHub Docs - About - commit signature verification `_. - - .. tip:: - - If you use SSH keys to sign your commits, make sure to add a "Signing Key" - type in your GitHub account. See - [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) - for more information. - -Code ----- - -Formatting and linting -~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your linting configuration setup or drop if excessive - -ACME relies on these formatting and linting tools: - -- `TODO: Tool 1 `_ -- `TODO: Tool 2 `_ - - -To configure and run them: - -.. code-block:: console - - TODO: lint command 1 - TODO: lint command 2 - - -Structure -~~~~~~~~~ - -- **Check linked code elements**: - Check that coupled code elements, files and directories are adjacent. - For instance, store test data close to the corresponding test code. - -- **Group variable declaration and initialisation**: - Declare and initialise variables together - to improve code organisation and readability. - -- **Split large expressions**: - Break down large expressions - into smaller self-explanatory parts. - Use multiple variables where appropriate - to make the code more understandable - and choose names that reflect their purpose. - -- **Use blank lines for logical separation**: - Insert a blank line between two logically separate sections of code. - This improves its structure and makes it easier to understand. - -- **Avoid nested conditions**: - Avoid nesting conditions to improve readability and maintainability. - -- **Remove dead code and redundant comments**: - Drop unused or obsolete code and comments. - This promotes a cleaner code base and reduces confusion. - -- **Normalise symmetries**: - Treat identical operations consistently, using a uniform approach. - This also improves consistency and readability. - - -Best practices -~~~~~~~~~~~~~~ - -.. TODO: Update with your best practices or drop if excessive - - -Tests ------ - -.. TODO: Update with your testing framework details or drop if excessive - -All code contributions must include tests. - -To run the tests locally before submitting your changes: - -.. code-block:: console - - TODO: test command 1 - TODO: test command 2 - - -Documentation -------------- - -ACME's documentation is stored in the ``DOCDIR`` directory of the repository. -It is based on the `Canonical Starter Pack -`_ -and hosted on `Read the Docs `_. - -For syntax help and guidelines, -refer to the Canonical syntax guides -(:ref:`reStructuredText ` and :ref:`MyST `). - -In structuring, -the documentation employs the `Diátaxis `_ approach. - -To run the documentation locally before submitting your changes: - -.. code-block:: console - - make run - - -Automatic checks -~~~~~~~~~~~~~~~~ - -GitHub runs automatic checks on the documentation -to verify spelling, validate links and suggest inclusive language. - -You can (and should) run the same checks locally: - -.. code-block:: console - - make spelling - make linkcheck - make woke diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 7050375..94f7b6d 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Explore the essential guides and procedures in Canonical's Starter Pack. + :description: Explore the essential guides and procedures in the Sphinx Stack. .. _how-to-guides: @@ -7,14 +7,15 @@ How-to guides ============= -These guides will walk you through the processes involving setting up, -maintaining, and contributing to the Starter Pack. +These guides will walk you through the processes involving setting up, maintaining, and +contributing to the Sphinx Stack. + Basic setup and maintenance --------------------------- -Set up, configure, update, and customize your project to keep it organized and aligned with -your documentation needs. +Set up, configure, update, and customize your project to keep it organized and aligned +with your documentation needs. .. toctree:: :maxdepth: 1 @@ -23,18 +24,19 @@ your documentation needs. build-and-preview run-documentation-checks publish-on-rtd - update-starter-packs/index.rst + update-sphinx-stack/index.rst troubleshooting + Optional features and customisation ----------------------------------- -As your documentation grows, you may need more advanced features to support richer content. This -can include customising the build system, adding diagrams as code, rendering API references, interactive -tables, and custom HTML. +As your documentation grows, you may need more advanced features to support richer +content. This can include customising the build system, adding diagrams as code, +rendering API references, interactive tables, and custom HTML. -While some of these features are available by default in the Starter Pack, others may require additional -extensions. +While some of these features are available by default in the Sphinx Stack, others may +require additional extensions. The following guides will help you get started: diff --git a/docs/how-to/optional-customisation/add-documentation-testing.rst b/docs/how-to/optional-customisation/add-documentation-testing.rst index d89b651..2f5ca2b 100644 --- a/docs/how-to/optional-customisation/add-documentation-testing.rst +++ b/docs/how-to/optional-customisation/add-documentation-testing.rst @@ -10,8 +10,9 @@ It's challenging to keep documentation in sync with products as they evolve. Thi process is aided by *Spread*, a test distributor that can work through your documentation and report failures in GitHub workflows. -By using Spread tests, you can rely on the tests as the source of truth for commands -in your documentation, enabling fully tested documentation at build time. +By using Spread tests, you can rely on the tests as the source of truth for commands in +your documentation, enabling fully tested documentation at build time. + What you'll need ---------------- @@ -25,11 +26,12 @@ What you'll need `Go install method `_ recommended in the Spread README to install Spread. + Create a test suite ------------------- -From the root of your project, create the file ``spread.yaml`` and insert the -following contents: +From the root of your project, create the file ``spread.yaml`` and insert the following +contents: .. code-block:: yaml :caption: project_name/spread.yaml @@ -38,12 +40,11 @@ following contents: path: /project_name -Match the ``project`` name to your main directory's name. -The ``path`` designates the directory where the Spread -materials exist. +Match the ``project`` name to your main directory's name. The ``path`` designates the +directory where the Spread materials exist. -So that Spread knows about your tests, add the -following section to the end of ``spread.yaml``: +So that Spread knows about your tests, add the following section to the end of +``spread.yaml``: .. code-block:: yaml :caption: project_name/spread.yaml @@ -59,12 +60,12 @@ following section to the end of ``spread.yaml``: systems: - ubuntu-24.04-64 -The ``suites`` section is how you tell Spread about the various Spread tests in -your project along with the systems you want Spread to use. -In this example, Spread looks for tests in the ``project_name/tests/spread`` directory and -runs them on Ubuntu 24.04. -If you create a new ``task.yaml`` file in a different directory, -remember to add a corresponding suite for it in ``spread.yaml``. +The ``suites`` section is how you tell Spread about the various Spread tests in your +project along with the systems you want Spread to use. In this example, Spread looks for +tests in the ``project_name/tests/spread`` directory and runs them on Ubuntu 24.04 LTS. +If you create a new ``task.yaml`` file in a different directory, remember to add a +corresponding suite for it in ``spread.yaml``. + Set up the Multipass backend ---------------------------- @@ -131,28 +132,27 @@ Copy the following ``backends`` section of ``spread.yaml`` between the ``path`` The ``backends`` section contains the following pieces: -* The backend is designated as ``type: adhoc`` as you must explicitly - script the procedure to allocate and discard the Multipass VM. -* The ``allocate`` section defines the image and name of the VM, launches the - VM, and sets up the proper SSH permissions Spread then logs in to the VM with - root permissions and inserts the Spread test. The last two lines tell Spread the - IP address of the Multipass VM and set the environment variable ``ADDRESS``. -* The ``discard`` section deletes the Multipass VM once the Spread test - has finished running. -* The ``systems`` key notes which systems the backend uses. Note that this key - must match the ``systems`` used by at least one test under ``suites``. +* The backend is designated as ``type: adhoc`` as you must explicitly script the + procedure to allocate and discard the Multipass VM. +* The ``allocate`` section defines the image and name of the VM, launches the VM, and + sets up the proper SSH permissions Spread then logs in to the VM with root permissions + and inserts the Spread test. The last two lines tell Spread the IP address of the + Multipass VM and set the environment variable ``ADDRESS``. +* The ``discard`` section deletes the Multipass VM once the Spread test has finished + running. +* The ``systems`` key notes which systems the backend uses. Note that this key must + match the ``systems`` used by at least one test under ``suites``. + Create a Spread task -------------------- -Put your Spread files alongside your project's existing tests. -The rest of this guide assumes they're in a top-level -``tests/spread`` directory. +Put your Spread files alongside your project's existing tests. The rest of this guide +assumes they're in a top-level ``tests/spread`` directory. -Each Spread test requires a dedicated ``task.yaml`` file that contains -all the commands you want to test. A single ``task.yaml`` can help you -validate an entire assumed workflow, for instance, -an end-to-end tutorial. +Each Spread test requires a dedicated ``task.yaml`` file that contains all the commands +you want to test. A single ``task.yaml`` can help you validate an entire assumed +workflow, for instance, an end-to-end tutorial. An example ``task.yaml`` file is shown below: @@ -171,39 +171,40 @@ An example ``task.yaml`` file is shown below: echo "This is the second command that Spread will run" -The ``summary`` section contains a brief description of the documentation you're testing, -the ``prepare`` section contains any initial setup your test needs, -and the ``execute`` section contains your documentation's commands. -The ``kill-timeout`` option has a default of 10 minutes and doesn't need to be -included if you expect your test to complete in that time frame. +The ``summary`` section contains a brief description of the documentation you're +testing, the ``prepare`` section contains any initial setup your test needs, and the +``execute`` section contains your documentation's commands. The ``kill-timeout`` option +has a default of 10 minutes and doesn't need to be included if you expect your test to +complete in that time frame. .. note:: - For a real-world example, see ``task.yaml`` for - `the Rockcraft Go tutorial. `_ + For a real-world example, see ``task.yaml`` for + `the Rockcraft Go tutorial. `_ + Include the tested commands in documentation -------------------------------------------- -By using the ``literalinclude`` directive in Sphinx, you can insert the -exact commands from ``task.yaml`` in your documentation file. +By using the ``literalinclude`` directive in Sphinx, you can insert the exact commands +from ``task.yaml`` in your documentation file. For example, consider the following ``task.yaml`` file: .. code-block:: yaml :caption: task.yaml - summary: Clone and build the Starter Pack + summary: Clone and build the Sphinx STack kill-timeout: 5m execute: | - # [docs:clone-starter-pack] - git clone https://github.com/canonical/sphinx-docs-starter-pack.git - # [docs:clone-starter-pack-end] + # [docs:clone-sphinx-stack] + git clone https://github.com/canonical/sphinx-stack.git + # [docs:clone-sphinx-stack-end] # [docs:build-documentation] - cd sphinx-docs-starter-pack/docs + cd sphinx-stack/docs make run # [docs:build-documentation-end] @@ -217,15 +218,15 @@ Include the commands from ``task.yaml`` in your documentation with: .. code-block:: rst :caption: Example ``literalinclude`` blocks - Clone the Starter Pack: + Clone the Sphinx Stack: .. literalinclude:: relative-path-to/task.yaml :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] + :start-after: [docs:clone-sphinx-stack] + :end-before: [docs:clone-sphinx-stack-end] :dedent: 2 - Enter the ``docs`` folder and build the project: + Enter the ``docs`` directory and build the project: .. literalinclude:: relative-path-to/task.yaml :language: bash @@ -239,16 +240,16 @@ Include the commands from ``task.yaml`` in your documentation with: .. code-block:: md :caption: Example ``literalinclude`` blocks - Clone the Starter Pack: + Clone the Sphinx Stack: ```{literalinclude} relative-path-to/task.yaml :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] + :start-after: [docs:clone-sphinx-stack] + :end-before: [docs:clone-sphinx-stack-end] :dedent: 2 ``` - Enter the `docs` folder and build the project: + Enter the `docs` directory and build the project: ```{literalinclude} relative-path-to/task.yaml :language: bash @@ -258,8 +259,9 @@ Include the commands from ``task.yaml`` in your documentation with: ``` By using the options ``:start-after:`` and ``:end-before:``, the documentation file -sources and includes all commands appearing in ``task.yaml`` between the -specified lines. +sources and includes all commands appearing in ``task.yaml`` between the specified +lines. + Run tests locally ----------------- @@ -270,8 +272,7 @@ List all available Spread tests in the code repository: spread --list -The terminal should respond with all the tests defined in ``spread.yaml``. -For example: +The terminal should respond with all the tests defined in ``spread.yaml``. For example: .. terminal:: :dir: project_name @@ -280,8 +281,8 @@ For example: multipass:ubuntu-24.04-64:tests/spread/example_documentation_test -Run all Spread tests locally with ``spread``. You can also run a single -Spread test by specifying: +Run all Spread tests locally with ``spread``. You can also run a single Spread test by +specifying: .. code-block:: bash @@ -290,6 +291,7 @@ Spread test by specifying: Depending on the complexity of your test, Spread can take several minutes to complete. The ``-vv -debug`` flags provide useful debugging information as the test runs. + Check the results ----------------- @@ -304,9 +306,8 @@ If the test is successful, the terminal will output something similar to the fol 2025-02-04 16:17:10 Aborted tasks: 0 Another sign of a successful test is whether the Multipass VM was deleted as expected. -Check by running :code:`multipass list`, and if the Spread test was successful -(and you have no other Multipass VMs created at the time), the terminal should -respond with: +Check by running ``multipass list``, and if the Spread test was successful (and you have +no other Multipass VMs created at the time), the terminal should respond with: .. terminal:: :dir: project_name @@ -315,9 +316,9 @@ respond with: No instances found. -If the Spread test failed, then the ``-debug`` flag will open a shell into the -Multipass VM so that additional debugging can happen. In that case, the terminal -will output something similar to the following: +If the Spread test failed, then the ``-debug`` flag will open a shell into the Multipass +VM so that additional debugging can happen. In that case, the terminal will output +something similar to the following: .. terminal:: :output-only: diff --git a/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst b/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst index 469c3ea..1248f62 100644 --- a/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst +++ b/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to bridge the build of Canonical's Starter Pack and a parent project's build. + :description: How to bridge the build of the Sphinx Stack and a parent project's build. :relatedlinks: [pip and dependency groups](https://pip.pypa.io/en/stable/user_guide/#dependency-groups), [uv and dependency groups](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups), [Poetry and dependency groups](https://python-poetry.org/docs/managing-dependencies#dependency-groups) @@ -12,7 +12,7 @@ Bridge project and documentation builds .. If more parent projects and build systems are tested, make the introduction general and add tabs to each of the steps -The Starter Pack can be used as a standalone docs repository, or embedded inside a +The Sphinx Stack can be used as a standalone docs repository, or embedded inside a parent project. This guide demonstrates how to bridge the docs build with a Python project's main build. Once bridged, project contributors can install, build, and check the docs from the root of the project with the main build system. @@ -34,7 +34,7 @@ capable of adding targets that call other systems. When shimmed, the docs target The bridge also **merges the virtual environments**, removing the need for a separate docs environment. This change is optional but recommended. To combine environments, your -project must provide **Python 3.11** or higher to the Starter Pack. Any Python +project must provide **Python 3.11** or higher to the Sphinx Stack. Any Python dependency manager will do, and this guide illustrates with three: - pip 25.1 and higher @@ -135,9 +135,9 @@ environment fed by three dependency groups in ``pyproject.toml``: - ``dev`` for development builds - ``docs`` for extra docs packages that your project needs -- ``docs-starter-pack`` for the core docs packages set by the Starter Pack +- ``docs-sphinx-stack`` for the core docs packages set by the Sphinx Stack -First, add the dependency groups. The docs group should depend on the Starter Pack +First, add the dependency groups. The docs group should depend on the Sphinx Stack group: .. code-block:: toml @@ -149,9 +149,9 @@ group: ] docs = [ # Packages for extra docs features - {include-group = "docs-starter-pack"}, + {include-group = "docs-sphinx-stack"}, ] - docs-starter-pack = [ + docs-sphinx-stack = [ # Core docs packages ] @@ -162,7 +162,7 @@ the ``dev`` dependency group. If your project needs extra docs features, like the Mermaid or LaTeX Sphinx extensions, add their packages to the ``docs`` group. -Copy the contents of ``docs/requirements.txt`` into the ``docs-starter-pack`` group. +Copy the contents of ``docs/requirements.txt`` into the ``docs-sphinx-stack`` group. In the main build, override the docs installation target to install the ``docs`` dependency group, then make the project's ``setup`` target depend on the docs target. In @@ -264,6 +264,7 @@ In the example project, the main build calls the targets like this: $(MAKE) -C docs $(@:docs-%=%) --no-print-directory .. admonition:: Variables and Makefiles + :class: note When calling another Makefile with ``$(MAKE) -C``, also known as a sub-Make call, variables with default values in the child Makefile won't be overridden. To override @@ -277,6 +278,7 @@ In the example project, the main build calls the targets like this: $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" + .. _how-to-bridge-project-builds-adjust-rtd-build: Adjust the Read the Docs build @@ -289,7 +291,8 @@ same build targets that developers use locally. If you use an uncommon system, you might need to install it during the workflow's ``create_environment`` job. -If you merged the virtual environments, make sure to set ``DOCS_VENVDIR=${READTHEDOCS_VIRTUALENV_PATH}`` in all commands. +If you merged the virtual environments, make sure to set +``DOCS_VENVDIR=${READTHEDOCS_VIRTUALENV_PATH}`` in all commands. Here's what it looks like in the example project: @@ -318,8 +321,8 @@ Here's what it looks like in the example project: Adjust the doc workflows ------------------------ -If your project uses the Starter Pack's docs workflows *and* Make, adjust the workflows -to use the bridged targets. +If your project uses the Sphinx Stack workflows *and* Make, adjust the workflows to use +the bridged targets. For the main checks, override the target names and paths through the `workflow inputs `_: diff --git a/docs/how-to/optional-customisation/custom-html-templates.md b/docs/how-to/optional-customisation/custom-html-templates.md index ec7c819..7d0ff86 100644 --- a/docs/how-to/optional-customisation/custom-html-templates.md +++ b/docs/how-to/optional-customisation/custom-html-templates.md @@ -8,21 +8,26 @@ myst: # Use custom HTML templates -If the default template in the Starter Pack doesn't fully meet your needs -- whether you want a unique layout, a custom header or footer, or a specialized sidebar for certain pages -- you can create and use a custom template for your project. +If the default template in the Sphinx Stack doesn't fully meet your needs -- whether you +want a unique layout, a custom header or footer, or a specialized sidebar for certain +pages -- you can create and use a custom template for your project. -This guide shows you how to extend or override the default templates in the Starter Pack to tailor the look and structure of your documentation. +This guide shows you how to extend or override the default templates in the Sphinx Stack +to tailor the look and structure of your documentation. ```{note} -Base template customizations can be made to your documentation. -However, they are not officially supported by the team maintaining the Starter Pack. -Use them at your own discretion. +Base template customizations can be made to your documentation. However, they are not +officially supported by the team maintaining the Spinx Stack. Use them at your own +discretion. ``` ## Setup -First, create the {file}`docs/_templates` directory; all your custom templates will need to be stored in this folder. +First, create the `docs/_templates` directory; all your custom templates will need to be +stored in this directory. -Then uncomment this line in {file}`docs/conf.py` so your project will use local templates (where available): +Then uncomment this line in `docs/conf.py` so your project will use local templates +(where available): ```{code-block} py :caption: conf\.py @@ -30,24 +35,29 @@ Then uncomment this line in {file}`docs/conf.py` so your project will use local templates_path = ["_templates"] ``` -In most cases, you will need to copy the default templates from the [canonical-sphinx theme] as a starting point and edit as needed. +In most cases, you will need to copy the default templates from the [canonical-sphinx +theme] as a starting point and edit as needed. ```{seealso} -Sphinx uses the Jinja templating engine for its HTML templates; see the [Jinja template syntax reference] for more details. +Sphinx uses the Jinja templating engine for its HTML templates; see the +[Jinja template syntax reference] for more details. ``` ## Use custom template for all pages -Sphinx looks for a template called {file}`page.html` as the entry point and main page template for documentation pages. -To customize your project's look and structure, check this file and determine which parts -- such as the header, footer, or sidebars -- need to be edited or overridden. +Sphinx looks for a template called `page.html` as the entry point and main page template +for documentation pages. To customize your project's look and structure, check this file +and determine which parts -- such as the header, footer, or sidebars -- need to be +edited or overridden. Here are some examples. ### Remove on-page TOC -To remove the on-page TOC in the right sidebar, make a copy of [page.html] in the {file}`docs/_templates` folder, and remove the applicable lines. -This will apply to all pages. +To remove the on-page TOC in the right sidebar, make a copy of [page.html] in the +`docs/_templates` directory, and remove the applicable lines. This will apply to all +pages. ```{code-block} html :caption: page.html @@ -75,7 +85,8 @@ This will apply to all pages. ### Add icon for GitHub link in header -To customize the default header by adding an icon for the GitHub link, first make a copy of [header.html] in the {file}`docs/_templates` folder. +To customize the default header by adding an icon for the GitHub link, first make a copy +of [header.html] in the `docs/_templates` directory. Then modify the conditional statement related to the GitHub URL with your code. @@ -105,16 +116,21 @@ Then modify the conditional statement related to the GitHub URL with your code. ## Use custom template for specific pages -If you want to use a custom template for specific pages in your project, you can do so by using conditional logic in {file}`page.html`. +If you want to use a custom template for specific pages in your project, you can do so +by using conditional logic in `page.html`. -First, create the base template with your modifications (e.g. {file}`special-header.html`, {file}`special-page.html`) and place it in the {file}`docs/_templates` folder. +First, create the base template with your modifications (e.g. `special-header.html`, +`special-page.html`) and place it in the `docs/_templates` directory. Next, make a copy of [page.html]. ### Partial template changes -To make partial changes (e.g. custom header) to specific pages, modify only the relevant parts of {file}`page.html` where you want the custom layout or behavior to apply. -For example, wrap the body block in a conditional statement so the custom header (e.g. {file}`special-header.html`) applies only to the "how-to/custom-templates" and "how-to/build" page. +To make partial changes (e.g. custom header) to specific pages, modify only the relevant +parts of `page.html` where you want the custom layout or behavior to apply. For example, +wrap the body block in a conditional statement so the custom header (e.g. +`special-header.html`) applies only to the "how-to/custom-templates" and "how-to/build" +page. ```{code-block} html :emphasize-lines: 2-6 @@ -132,8 +148,10 @@ For example, wrap the body block in a conditional statement so the custom header ### Whole template changes -To make changes to the whole template (e.g. a custom layout for a landing page or marketing page), modify the `extends` statement in {file}`page.html` to specify the pages that will use different templates. -For example, the {file}`special-page.html` template applies only to the "how-to/customise" and "how-to/diagrams-as-code" page. +To make changes to the whole template (e.g. a custom layout for a landing page or +marketing page), modify the `extends` statement in `page.html` to specify the pages that +will use different templates. For example, the `special-page.html` template applies only +to the "how-to/customise" and "how-to/diagrams-as-code" page. ```{code-block} html :caption: _templates/page.html @@ -146,7 +164,7 @@ For example, the {file}`special-page.html` template applies only to the "how-to/ ``` ```{note} -The pages "how-to/customise" and "how-to/diagrams-as-code" will use {file}`special-page.html` as the base template, but all other blocks (e.g. footer, body, etc) will follow the default {file}`page.html`. +The pages "how-to/customise" and "how-to/diagrams-as-code" will use `special-page.html` as the base template, but all other blocks (e.g. footer, body, etc) will follow the default `page.html`. ``` % LINKS diff --git a/docs/how-to/optional-customisation/customise-pdf.rst b/docs/how-to/optional-customisation/customise-pdf.rst index ed90eb0..8405469 100644 --- a/docs/how-to/optional-customisation/customise-pdf.rst +++ b/docs/how-to/optional-customisation/customise-pdf.rst @@ -9,134 +9,185 @@ Customise PDF output Overview -------- -The Starter Pack supports PDF output via LaTeX using the ``make pdf`` command. This build process relies on system packages, Sphinx configurations, and a LaTeX template from the ``canonical-sphinx`` extension. +The Sphinx Stack supports PDF output via LaTeX using the ``make pdf`` command. This +build process relies on system packages, Sphinx configurations, and a LaTeX template +from the ``canonical-sphinx`` extension. Customising PDF output involves two levels of configuration: -* **Sphinx configuration**: built-in options for configuring LaTeX build process in :file:`conf.py`, for example: the engine used to generate the PDF, output file name, and input file paths. -* **LaTeX configuration**: the LaTeX packages, styling, and configuration for the PDF output, set through the :literalref:`latex_elements ` dictionary in the project :file:`conf.py`. In the starter-pack, a default set of LaTeX elements is provided by the ``canonical-sphinx`` extension. Changing the LaTeX configuration requires overriding the default values loaded from the extension. +* **Sphinx configuration**: built-in options for configuring LaTeX build process in + ``conf.py``, for example: the engine used to generate the PDF, output file name, and + input file paths. +* **LaTeX configuration**: the LaTeX packages, styling, and configuration for the PDF + output, set through the :literalref:`latex_elements + ` + dictionary in the project ``conf.py``. In the Sphinx Stack, a default set of LaTeX + elements is provided by the ``canonical-sphinx`` extension. Changing the LaTeX + configuration requires overriding the default values loaded from the extension. -This guide covers common practices and tips for customising PDF output from your project using the Starter Pack and the ``canonical-sphinx`` extension. +This guide covers common practices and tips for customising PDF output from your project +using the Sphinx Stack and the ``canonical-sphinx`` extension. For basic instructions about building the PDF, see :ref:`build-and-preview`. + Configure document properties ----------------------------- -The :literalref:`latex_documents ` variable in the Sphinx :file:`conf.py` file controls properties of the intermediate LaTeX file and the final PDF output. The values are defined in a tuple of six elements: +The :literalref:`latex_documents +` +variable in the Sphinx ``conf.py`` file controls properties of the intermediate LaTeX +file and the final PDF output. The values are defined in a tuple of six elements: .. code-block:: python - latex_documents = [ - ( - 'startdocname', # Root document (e.g., 'index' or 'pdf-index') - 'targetname.tex', # Output LaTeX file name (no spaces) - 'title', # Document title (can be empty to use the root doc's title) - 'author', # Author name(s). - 'theme', # Document type: 'manual' or 'howto' - True, # toctree_only: if True, only include docs in toctree - ), - ] - -* ``startdocname``: The root document for the PDF (without the .rst extension). -* ``targetname``: The filename for the generated LaTeX source file. The PDF file name is derived from this filename with the ``.pdf`` extension. Blank space characters are not allowed. + latex_documents = [ + ( + 'startdocname', # Root document (e.g., 'index' or 'pdf-index') + 'targetname.tex', # Output LaTeX file name (no spaces) + 'title', # Document title (can be empty to use the root doc's title) + 'author', # Author name(s). + 'theme', # Document type: 'manual' or 'howto' + True, # toctree_only: if True, only include docs in toctree + ), + ] + +* ``startdocname``: The root document for the PDF (without the ``.rst`` extension). +* ``targetname``: The filename for the generated LaTeX source file. The PDF file name is + derived from this filename with the ``.pdf`` extension. Blank space characters are not + allowed. * ``title``: The title for the PDF document on the cover page. * ``author``: The author(s) of the document. Use ``\\and`` to separate multiple authors. * ``theme``: Either ``manual`` or ``howto``. - * ``manual``: This is the default and is intended for comprehensive, book-style documentation. It produces a PDF with chapters, sections, and a table of contents. Use this for user guides, reference manuals, or any documentation that should be structured as a book. - * ``howto``: This type is for shorter, task-oriented documents. It produces a simpler PDF without chapters, and is best for single-topic guides or tutorials. + * ``manual``: This is the default and is intended for comprehensive, book-style + documentation. It produces a PDF with chapters, sections, and a table of contents. + Use this for user guides, reference manuals, or any documentation that should be + structured as a book. + * ``howto``: This type is for shorter, task-oriented documents. It produces a simpler + PDF without chapters, and is best for single-topic guides or tutorials. -* ``toctree_only``: Boolean. If set to True, the ``startdocname`` document itself is not included in the output, only the documents referenced by the ``toctree`` directive are included. This is useful for creating a PDF-specific index file. +* ``toctree_only``: Boolean. If set to True, the ``startdocname`` document itself is not + included in the output, only the documents referenced by the ``toctree`` directive are + included. This is useful for creating a PDF-specific index file. -For more details, see `latex_documents `_ in the Sphinx documentation. +For more details, see `latex_documents +`_ +in the Sphinx documentation. Change PDF document filename ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the PDF output filename is derived from the ``project`` name in the :file:`conf.py` file: lowercase characters with blank spaces removed. +By default, the PDF output filename is derived from the ``project`` name in the +``conf.py`` file: lowercase characters with blank spaces removed. -To override the filename, update the second element (``targetname``) of the ``latex_documents`` tuple in :file:`conf.py`. The following example shows how to replace blank spaces in the project name with underscores: +To override the filename, update the second element (``targetname``) of the +``latex_documents`` tuple in ``conf.py``. The following example shows how to replace +blank spaces in the project name with underscores: .. code-block:: python - latex_documents = [ - ( - 'index', - f"{project.replace(' ', '_')}.tex", - '', - 'Author Name', - 'manual', - True, - ), - ] + latex_documents = [ + ( + 'index', + f"{project.replace(' ', '_')}.tex", + '', + 'Author Name', + 'manual', + True, + ), + ] + Change PDF document title ~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the PDF title on the cover page comes from the title of the main index document. To override it, update the third element (title) of the ``latex_documents`` tuple in :file:`conf.py`. Use an empty string (``''``) to keep the default behaviour. +By default, the PDF title on the cover page comes from the title of the main index +document. To override it, update the third element (title) of the ``latex_documents`` +tuple in ``conf.py``. Use an empty string (``''``) to keep the default behaviour. + Use a different index document for PDF builds ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Because the PDF output has a different usage and structure from the HTML output, it is sometimes useful to create a PDF-specific index document. For example, you may want to create a PDF-specific index file that includes only a subset of the pages in the HTML index. +Because the PDF output has a different usage and structure from the HTML output, it is +sometimes useful to create a PDF-specific index document. For example, you may want to +create a PDF-specific index file that includes only a subset of the pages in the HTML +index. To use a different index document for PDF builds: -1. Create a PDF-specific index document, for example, :file:`pdf-index.rst`. -2. Update the first element (``startdocname``) of the ``latex_documents`` tuple in :file:`conf.py` to point to the new index document. -3. Set the last element (``toctree_only``) of the ``latex_documents`` tuple in :file:`conf.py` to ``False`` to ensure only referenced documents are included in the PDF output. -4. Exclude the PDF-specific index document from the HTML build. This is done by changing the ``exclude_patterns`` list in :file:`conf.py`: +#. Create a PDF-specific index document, for example, ``pdf-index.rst``. +#. Update the first element (``startdocname``) of the ``latex_documents`` tuple in + ``conf.py`` to point to the new index document. +#. Set the last element (``toctree_only``) of the ``latex_documents`` tuple in + ``conf.py`` to ``False`` to ensure only referenced documents are included in the PDF + output. +#. Exclude the PDF-specific index document from the HTML build. This is done by changing + the ``exclude_patterns`` list in ``conf.py``: .. code-block:: python # Identify the Sphinx builder being used if '-b' in sys.argv: - builder = sys.argv[sys.argv.index('-b') + 1] + builder = sys.argv[sys.argv.index('-b') + 1] elif '-M' in sys.argv: - builder = sys.argv[sys.argv.index('-M') + 1] + builder = sys.argv[sys.argv.index('-M') + 1] else: - builder = 'html' # default builder + builder = 'html' # default builder # Exclude the PDF-specific index from the HTML build if builder in ['html', 'dirhtml']: - exclude_patterns.append('pdf-index.rst') + exclude_patterns.append('pdf-index.rst') -Check both the HTML and PDF outputs to confirm that different index documents are used for each output. +Check both the HTML and PDF outputs to confirm that different index documents are used +for each output. .. note:: - The order and hierarchy of your ``toctree`` entries determine the chapters and sections in the PDF. - Any headings placed before the main ``toctree`` in your root document will cause all referenced documents to be nested under that heading in the PDF. To avoid this, do not add extra headings before the ``toctree``. + The order and hierarchy of your ``toctree`` entries determine the chapters and + sections in the PDF. + + Any headings placed before the main ``toctree`` in your root document will cause all + referenced documents to be nested under that heading in the PDF. To avoid this, do + not add extra headings before the ``toctree``. Override the LaTeX template ----------------------------- -The LaTeX template is a text file in the ``canonical-sphinx`` extension that provides the default styling and layout of the PDF document. The template contains a Python dictionary of LaTeX elements, which will be imported by Sphinx when the PDF is built. +The LaTeX template is a text file in the ``canonical-sphinx`` extension that provides +the default styling and layout of the PDF document. The template contains a Python +dictionary of LaTeX elements, which will be imported by Sphinx when the PDF is built. -Any additions or changes to the default settings of LaTeX elements in the PDF document requires overriding the default template. +Any additions or changes to the default settings of LaTeX elements in the PDF document +requires overriding the default template. -1. Download the default template file `latex_elements_template.txt `_ from the ``canonical/canonical-sphinx`` GitHub repository, and save it to your project directory. For example, at :file:`.sphinx/latex_elements_custom.txt`. - -2. In the Python dictionary, add or modify the LaTeX elements you want to change. Details of changing the dictionary are covered in the sub-sections below. - -3. In your project :file:`conf.py`, add or update the ``latex_elements`` dictionary to load the local override of the LaTeX template. Change the file path to the location of your local override file. +#. Download the default template file `latex_elements_template.txt + `_ + from the ``canonical/canonical-sphinx`` GitHub repository, and save it to your + project directory. For example, at ``_dev/latex_elements_custom.txt``. +#. In the Python dictionary, add or modify the LaTeX elements you want to change. + Details of changing the dictionary are covered in the sub-sections below. +#. In your project's ``conf.py`` file, add or update the ``latex_elements`` dictionary + to load the local override of the LaTeX template. Change the file path to the + location of your local override file. .. code-block:: python - # Replace with the path to your local override file - latex_elements_file = ".sphinx/latex_elements_custom.txt" - - with open(latex_elements_file, "rt") as file: - latex_config = file.read() - if latex_elements == {}: - latex_elements = ast.literal_eval(latex_config) + # Replace with the path to your local override file + latex_elements_file = "_dev/latex_elements_custom.txt" + + with open(latex_elements_file, "rt") as file: + latex_config = file.read() + if latex_elements == {}: + latex_elements = ast.literal_eval(latex_config) .. warning:: - Defining other settings directly in ``latex_elements`` will override the values loaded from the template file or your local file. + Defining other settings directly in ``latex_elements`` will override the values + loaded from the template file or your local file. Add more LaTeX packages to the preamble @@ -147,89 +198,111 @@ You can use two methods to add additional LaTeX packages to the preamble: * Add the ``extrapackages`` key in your local template file: .. code-block:: python - :class: vale-ignore - :emphasize-lines: 3 + :class: vale-ignore + :emphasize-lines: 3 - { - ... - 'extrapackages': r'\usepackage{packagename}', - ... - } + { + ... + 'extrapackages': r'\usepackage{packagename}', + ... + } * Modify the values of the ``preamble`` key in your local template file. This is more flexible for adding LaTeX configurations and commands to the preamble. .. note:: - The format of the element values is a multi-line string, so use a raw string with the ``r`` prefix. + + The format of the element values is a multi-line string, so use a raw string with + the ``r`` prefix. Remove the table of contents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For a short, compact document where navigation is not needed, you may want to remove the table of contents from the PDF output. +For a short, compact document where navigation is not needed, you may want to remove the +table of contents from the PDF output. -To do this, provide a local copy of the default template file, and add a new key ``tableofcontents`` with an empty string as the value: +To do this, provide a local copy of the default template file, and add a new key +``tableofcontents`` with an empty string as the value: .. code-block:: python - :emphasize-lines: 3 + :emphasize-lines: 3 - { - ... - 'tableofcontents': '', - ... - } + { + ... + 'tableofcontents': '', + ... + } Include images or other assets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If the local template requires additional images or other assets, for example, a custom title page or header, the file paths must be added to the Sphinx :file:`conf.py` file to be included in the PDF build. +If the local template requires additional images or other assets, for example, a custom +title page or header, the file paths must be added to the Sphinx ``conf.py`` file to +be included in the PDF build. -Provide a ``latex_additional_files`` variable in :file:`conf.py` as a list of file paths to the additional assets. If the variable already exists, add the new file paths to the list. The paths should be relative to the :file:`conf.py` file. +Provide a ``latex_additional_files`` variable in your ``conf.py`` file as a list of file +paths to the additional assets. If the variable already exists, add the new file paths +to the list. The paths should be relative to the ``conf.py`` file. .. code-block:: python - # path relative to the conf.py file - latex_additional_files = [ - 'path/to/image.svg', - 'path/to/other-asset.pdf', - ] + # path relative to the conf.py file + latex_additional_files = [ + 'path/to/image.svg', + 'path/to/other-asset.pdf', + ] .. note:: - For better quality in the PDF output, it is recommended to use vector images (like SVG or PDF) rather than raster images (like PNG or JPEG). Raster images may lose quality when scaled up in the PDF. - Do not use ``.tex`` as suffix, otherwise the file is processed as source files for the PDF build process. Instead, use ``.tex.txt`` or ``.sty`` to avoid conflicts with the LaTeX build process. + For better quality in the PDF output, it is recommended to use vector images (like + SVG or PDF) rather than raster images (like PNG or JPEG). Raster images may lose + quality when scaled up in the PDF. + + Do not use ``.tex`` as suffix, otherwise the file is processed as source files for + the PDF build process. Instead, use ``.tex.txt`` or ``.sty`` to avoid conflicts + with the LaTeX build process. Use landscape layout ~~~~~~~~~~~~~~~~~~~~ -The PDF output uses portrait orientation by default. To use landscape orientation, you need to add more packages to the LaTeX preamble and use a specific LaTeX environment to rotate the content. +The PDF output uses portrait orientation by default. To use landscape orientation, you +need to add more packages to the LaTeX preamble and use a specific LaTeX environment to +rotate the content. -1. Add the ``extrapackages`` key to your local template file, and set the value to the ``pdflscape`` package: +#. Add the ``extrapackages`` key to your local template file, and set the value to the + ``pdflscape`` package: .. code-block:: python :emphasize-lines: 3 { - ... - 'extrapackages': r'\usepackage{pdflscape}', - ... + ... + 'extrapackages': r'\usepackage{pdflscape}', + ... } .. note:: - The format of the element values is a multi-line string, so use a raw string with the ``r`` prefix. -2. Use the landscape environment in your documentation source file, and only in the PDF output. + The format of the element values is a multi-line string, so use a raw string with + the ``r`` prefix. - Wherever you want a section (such as a wide table or figure) to appear in the landscape view, use the ``.. raw:: latex`` directive to include raw LaTeX code that opens and closes the landscape environment. Only the content between ``\begin{landscape}`` and ``\end{landscape}`` will be rotated: +#. Use the landscape environment in your documentation source file, and only in the PDF + output. + + Wherever you want a section (such as a wide table or figure) to appear in the + landscape view, use the ``.. raw:: latex`` directive to include raw LaTeX code that + opens and closes the landscape environment. Only the content between + ``\begin{landscape}`` and ``\end{landscape}`` will be rotated: .. code-block:: rst .. only:: latex - .. raw:: latex + .. raw:: latex - \begin{landscape} + \begin{landscape} .. list-table:: Example of a landscape table :header-rows: 1 @@ -243,28 +316,35 @@ The PDF output uses portrait orientation by default. To use landscape orientatio .. only:: latex - .. raw:: latex + .. raw:: latex - \end{landscape} + \end{landscape} Check PDF build log files ------------------------- -If you encounter an issue that requires further debugging, check the PDF build logs for more detailed error messages. The full logs are generated in the :file:`_build/latex` output directory, and then cleaned up after the build completes. +If you encounter an issue that requires further debugging, check the PDF build logs for +more detailed error messages. The full logs are generated in the ``_build/latex`` +output directory, and then cleaned up after the build completes. To temporarily save the log files for debugging: -1. Open the ``Makefile`` and locate the ``pdf`` target. Disable the cleanup step by commenting out the ``@rm -r $(BUILDDIR)/latex`` line. -2. Run the ``make pdf`` again. -3. Navigate to the output directory :file:`_build/latex` and check the ``*.log`` and ``*.tex`` files. -4. After debugging, restore the cleanup step by uncommenting the same line. +#. Open the ``Makefile`` and locate the ``pdf`` target. Disable the cleanup step by + commenting out the ``@rm -r $(BUILDDIR)/latex`` line. +#. Run the ``make pdf`` again. +#. Navigate to the output directory ``_build/latex`` and check the ``*.log`` and + ``*.tex`` files. +#. After debugging, restore the cleanup step by uncommenting the same line. .. warning:: - Keeping the build log files from the previous build might cause conflicts with the current build + Keeping the build log files from the previous build might cause conflicts with the + current build + Related ------- + - :ref:`build-and-preview` - :ref:`configure-your-project` diff --git a/docs/how-to/optional-customisation/enable-google-analytics.rst b/docs/how-to/optional-customisation/enable-google-analytics.rst index 269e0e7..36643e2 100644 --- a/docs/how-to/optional-customisation/enable-google-analytics.rst +++ b/docs/how-to/optional-customisation/enable-google-analytics.rst @@ -23,27 +23,27 @@ page interaction. The footer template provides a link for users to change their data collection preferences. -The process for sourcing these files depends on your Starter Pack version. Check which -version is listed in your project's ``docs/.sphinx/version`` file. +The process for sourcing these files depends on your Sphinx Stack version. Check which +version is listed in your project's ``docs/_dev/version`` file. -On Starter Pack 1.6 or higher +On Sphinx Stack 1.6 or higher ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Starting in version 1.6 of the Starter Pack, these templates are available by default. +Starting in version 1.6 of the Sphinx Stack, these templates are available by default. If you're on one of these versions, skip ahead to :ref:`update-your-configuration-file`. -On Starter Pack 1.5 or lower +On Sphinx Stack 1.5 or lower ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In version 1.5 of the Starter Pack and lower, the templates were sourced from a separate +In version 1.5 of the Sphinx Stack and lower, the templates were sourced from a separate repository. Download the latest version of the templates: -- :literalref:`header.html ` -- :literalref:`footer.html ` +- :literalref:`header.html ` +- :literalref:`footer.html ` Next, create a ``docs/_templates`` directory and move the templates into it. @@ -89,7 +89,7 @@ Update your configuration file Now that the templates are in place, you need to make Sphinx aware of them in your project's configuration file. -If you're on version 1.6 of the Starter Pack or higher, these lines already exist +If you're on version 1.6 of the Sphinx Stack or higher, these lines already exist in your configuration file. You only need to uncomment them in the following steps. In lower versions, you need to add them yourself. diff --git a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst b/docs/how-to/optional-customisation/external-referencing-intersphinx.rst index e872647..8154eac 100644 --- a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst +++ b/docs/how-to/optional-customisation/external-referencing-intersphinx.rst @@ -1,21 +1,24 @@ .. meta:: - :description: Configure references to external Sphinx projects with the Intersphinx extension. + :description: Configure references to external Sphinx projects with the Intersphinx extension. .. _how-to-link-docs-intersphinx: Link to other documentation sets with Intersphinx ================================================= -This guide provides instructions on how to set up external references using the Intersphinx extension. -Linking to external Sphinx-based documentation sets via hyperlinks is difficult to maintain. -Intersphinx provides a more robust alternative, linking to sections of other Sphinx projects based on -labels mapped out in an inventory list as ``objects.inv``. To effectively use Intersphinx, sections in -the target documentation set must have labels. +This guide provides instructions on how to set up external references using the +Intersphinx extension. Linking to external Sphinx-based documentation sets via +hyperlinks is difficult to maintain. Intersphinx provides a more robust alternative, +linking to sections of other Sphinx projects based on labels mapped out in an inventory +list as ``objects.inv``. To effectively use Intersphinx, sections in the target +documentation set must have labels. + Configure the extension ----------------------- -In the ``conf.py`` file in your docs directory, add or enable ``sphinx.ext.intersphinx`` under ``extensions``: +In the ``conf.py`` file in your docs directory, add or enable ``sphinx.ext.intersphinx`` +under ``extensions``: .. code-block:: python :caption: conf.py @@ -29,31 +32,33 @@ Then, connect to the other project in the ``intersphinx_mapping`` setting: .. code-block:: python - :caption: conf.py + :caption: conf.py - # Add configuration for intersphinx mapping - # Map only the Sphinx documentation sets that you need to link to from your docs set. - intersphinx_mapping = { - 'project-key': ('https://example.com', None) - } + # Add configuration for intersphinx mapping + # Map only the Sphinx documentation sets that you need to link to from your docs set. + intersphinx_mapping = { + 'project-key': ('https://example.com', None) + } Replace ``project-key`` with the internal identifier for the project that you'll specify -in the document markup. For example, if the identifier were ``chisel``, an Intersphinx link to it would be ``:external+chisel:ref:`target```. +in the document markup. For example, if the identifier were ``chisel``, an Intersphinx +link to it would be ``:external+chisel:ref:`target```. + +The value after the URI points to a custom path location. If a project stores its +``objects.inv`` at a special location, replace ``None`` with the path to it. -The value after the URI points to a custom path location. If a project stores its ``objects.inv`` at a special location, replace ``None`` with the path to it. Check the external target labels -------------------------------- -To check external target page labels, either search the project source code -manually or inspect the ``objects.inv`` file. In this file, each section has a -unique label. +To check external target page labels, either search the project source code manually or +inspect the ``objects.inv`` file. In this file, each section has a unique label. To inspect the file manually, run: .. code-block:: bash - source .sphinx/venv/bin/activate + source .venv/bin/activate python -m sphinx.ext.intersphinx https://example.com/objects.inv The output lists the different pages and their labels: @@ -61,14 +66,6 @@ The output lists the different pages and their labels: .. terminal:: :output-only: - lrd:doc - explanation/faq FAQ : explanation/faq/ - explanation/index Explanation : explanation/ - explanation/mode-of-operation How Chisel works : explanation/mode-of-operation/ - lrd:label - chise_faq FAQ : explanation/faq/#chise-faq - chisel-releases_ref chisel-releases : reference/chisel-releases/#chisel-releases-ref - chisel_helloworld_tutorial Getting started with Chisel : tutorial/getting-started/#chisel-helloworld-tutorial std:doc explanation/faq FAQ : explanation/faq/ explanation/index Explanation : explanation/ @@ -80,18 +77,19 @@ The output lists the different pages and their labels: The appropriate labels are under ``std:label``. + Add references to the text -------------------------- To add in-line references, follow this structure: .. list-table:: - :header-rows: 1 - :widths: 20 80 - - * - Format - - Syntax - * - reST - - ``:external+project_key:ref:`an_external_target``` - * - MyST - - ``{ref}`project_key:an_external_target``` + :header-rows: 1 + :widths: 20 80 + + * - Format + - Syntax + * - reST + - ``:external+project_key:ref:`an_external_target``` + * - MyST + - ``{ref}`project_key:an_external_target``` diff --git a/docs/how-to/optional-customisation/interactive-tables.rst b/docs/how-to/optional-customisation/interactive-tables.rst index b6e3a8f..1376260 100644 --- a/docs/how-to/optional-customisation/interactive-tables.rst +++ b/docs/how-to/optional-customisation/interactive-tables.rst @@ -6,16 +6,22 @@ Add interactive data tables =========================== -Data-heavy documentation often benefits from tables that users can explore interactively. -The `Sphinx DataTables`_ extension provides interactive tables where users can sort columns and filter rows, making large datasets more navigable and useful. -For examples, see the extension's documentation. +Data-heavy documentation often benefits from tables that users can explore +interactively. The `Sphinx DataTables `__ +extension provides interactive tables where users can sort columns and filter rows, +making large datasets more navigable and useful. For examples, see the extension's +documentation. + +The extension isn't available by default in the Sphinx Stack. To read more about table +functionality that is available out of the box, see :ref:`Tables (MyST) +` and :ref:`Tables (reST) `. -The extension isn't available by default in the Starter Pack. To read more about table functionality that is available out of the box, see :ref:`Tables (MyST) ` and :ref:`Tables (reST) `. Include the ``sphinx-datatables`` extension ------------------------------------------- -To include the extension in your documentation, add ``sphinx-datatables`` to ``docs/requirements.txt``. +To include the extension in your documentation, add ``sphinx-datatables`` to +``docs/requirements.txt``. Then, add ``sphinx_datatables`` to the ``extensions`` list in ``docs/conf.py``. @@ -27,17 +33,17 @@ Make a table interactive by adding a special CSS class to the directive: .. code-block:: rst - .. csv-table:: - :class: sphinx-datatable - :file: /reuse/animals.csv - :header-rows: 1 + .. csv-table:: + :class: sphinx-datatable + :file: /how-to/assets/animals.csv + :header-rows: 1 .. tab-item:: MyST .. code-block:: none - ```{csv-table} - :class: sphinx-datatable - :file: /reuse/animals.csv - :header-rows: 1 - ``` + ```{csv-table} + :class: sphinx-datatable + :file: /how-to/assets/animals.csv + :header-rows: 1 + ``` diff --git a/docs/how-to/optional-customisation/mermaid-diagrams.md b/docs/how-to/optional-customisation/mermaid-diagrams.md index f9565e4..dce5761 100644 --- a/docs/how-to/optional-customisation/mermaid-diagrams.md +++ b/docs/how-to/optional-customisation/mermaid-diagrams.md @@ -9,22 +9,29 @@ relatedlinks: https://mermaid.js.org/intro/, https://mermaid.live/ # Create diagrams as code using Mermaid -Diagrams help users quickly understand and visualize complex ideas, but they can easily become outdated and difficult to maintain. -Creating diagrams as code solves this by keeping them alongside the software source, making updates and reviews simpler. +Diagrams help users quickly understand and visualize complex ideas, but they can easily +become outdated and difficult to maintain. Creating diagrams as code solves this by +keeping them alongside the software source, making updates and reviews simpler. -Mermaid is a popular choice that allows diagrams to be created, maintained, and updated directly in the documentation. -This guide explains how to set up the {doc}`sphinxcontrib-mermaid ` extension and use Mermaid diagrams in your documentation, with examples included. +Mermaid is a popular choice that allows diagrams to be created, maintained, and updated +directly in the documentation. This guide explains how to set up the +{doc}`sphinxcontrib-mermaid ` extension and use Mermaid +diagrams in your documentation, with examples included. ```{note} -While there are many other tools and/or approaches for creating diagrams in visualizations in your documentation (e.g. [C4 model], [Dia], [PlantUML], [Structurizr], etc), we only provide support for `sphinxcontrib-mermaid` in the Starter Pack. +While there are many other tools and/or approaches for creating diagrams in +visualizations in your documentation (e.g. [C4 model], [Dia], [PlantUML], [Structurizr], +etc), we only provide support for `sphinxcontrib-mermaid` in the Sphinx Stack. ``` ## Installation and setup -First, add the "sphinxcontrib-mermaid" extension to {file}`requirements.txt` so that it's installed as part of your Sphinx project dependencies: +First, add the sphinxcontrib-mermaid extension to your `requirements.txt` file so it's +installed as a dependency: ```{code-block} text :emphasize-lines: 6 + canonical-sphinx[full] packaging sphinxcontrib-svg2pdfconverter[CairoSVG] @@ -33,7 +40,7 @@ sphinx-sitemap sphinxcontrib-mermaid ``` -Then add "sphinxcontrib.mermaid" in the "extensions" list in `conf.py`: +Then add `sphinxcontrib.mermaid` to the `extensions` list in your `conf.py` file: ```{code-block} python extensions = [ @@ -42,31 +49,36 @@ extensions = [ ] ``` -You are now ready embed Mermaid diagrams and visualization in your documentation using the `mermaid` directive. +You are now ready embed Mermaid diagrams and visualization in your documentation using +the `mermaid` directive. ### Optional configuration -You can further configure Mermaid's default settings in your project's {file}`conf.py`, such as specifying the image output format (e.g., "png", "raw"), enabling zoom on diagrams, or pinning the [Mermaid version] used for rendering. +You can further configure Mermaid's default settings in your project's `conf.py`, such +as specifying the image output format (e.g., "png", "raw"), enabling zoom on diagrams, +or pinning the [Mermaid version] used for rendering. See [Mermaid configuration values] for more information. ## Add a new diagram -Use the `mermaid` directive to embed a Mermaid diagram into your documentation. -You start by declaring the type of diagram (e.g. "flowchart", "sequenceDiagram", "timeline", etc), followed by definition and contents. -It is also possible to specify additional configuration or custom styles, depending on the diagram type. +Use the `mermaid` directive to embed a Mermaid diagram into your documentation. You +start by declaring the type of diagram (e.g. `flowchart`, `sequenceDiagram`, `timeline`, +etc), followed by definition and contents. It is also possible to specify additional +configuration or custom styles, depending on the diagram type. Some examples will be covered below. ```{seealso} -See the [Mermaid - Diagram syntax] reference for details on the syntax and customization options for each diagram type. +See the [Mermaid - Diagram syntax] reference for details on the syntax and customization +options for each diagram type. ``` ### Flowchart diagram with default settings The left-to-right flowchart below uses the default Mermaid settings. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-flowchart-start :end-before: mermaid-diagram-flowchart-end ``` @@ -75,34 +87,37 @@ The left-to-right flowchart below uses the default Mermaid settings. The timeline diagram below uses a [pre-defined Mermaid theme]. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-timeline-start :end-before: mermaid-diagram-timeline-end ``` ### Sequence diagram with global custom CSS -The sequence diagram below has custom styling applied using a global CSS file. -A global CSS file enables the styles to be easily applied to all sequence diagrams, based on the classes defined in your stylesheet. -You can also use the global CSS file to customize the diagrams in dark mode. +The sequence diagram below has custom styling applied using a global CSS file. A global +CSS file enables the styles to be easily applied to all sequence diagrams, based on the +classes defined in your stylesheet. You can also use the global CSS file to customize +the diagrams in dark mode. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-sequence-start :end-before: mermaid-diagram-sequence-end ``` ### State diagram with image-specific styles -The state diagram below has image-specific custom styling applied using the [`classDef` keyword]. +The state diagram below has image-specific custom styling applied using the [`classDef` +keyword]. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-state-start :end-before: mermaid-diagram-state-end ``` ## Projects using Mermaid -Here are some Canonical projects that use Mermaid for diagramming in their documentation: +Here are some Canonical projects that use Mermaid for diagramming in their +documentation: - [Checkbox](https://canonical-checkbox.readthedocs-hosted.com/stable/explanation/remote/) - [cloud-init](https://docs.cloud-init.io/en/latest/explanation/boot.html) diff --git a/docs/how-to/optional-customisation/python-docstrings.md b/docs/how-to/optional-customisation/python-docstrings.md index d548c6c..730d103 100644 --- a/docs/how-to/optional-customisation/python-docstrings.md +++ b/docs/how-to/optional-customisation/python-docstrings.md @@ -8,24 +8,33 @@ myst: # Import docstrings with Sphinx `autodoc` -Module and function details are useful reference material to have in documentation, but the process of manually pulling all the necessary details over can become tedious. The [Sphinx `autodoc` extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) provides the capability to automatically pull in docstrings and module information for Python code. +Module and function details are useful reference material to have in documentation, but +the process of manually pulling all the necessary details over can become tedious. The +[Sphinx `autodoc` +extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) provides +the capability to automatically pull in docstrings and module information for Python +code. ## Prerequisites -To use the Sphinx `autodoc` extension with the Starter Pack, you need: +To use the Sphinx `autodoc` extension with the Sphinx Stack, you need: * Python module files located within the same repository as your documentation OR -* The code repository added as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) into the documentation repository +* The code repository added as a [Git + submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) into the documentation + repository ## Setup -In the {file}`conf.py` file in your docs directory, update the `sys.path` so that Sphinx can find your module files. At the top of the file, add a `sys.path.insert` that adds your `` directory: +In the `conf.py` file in your docs directory, update the `sys.path` so that Sphinx can +find your module files. At the top of the file, add a `sys.path.insert` that adds your +`` directory: ```{code-block} python -:caption: {file}`conf.py` +:caption: `conf.py` import sys from pathlib import Path @@ -36,10 +45,11 @@ absolute_code_path_str = str(absolute_code_path) sys.path.insert(0, absolute_code_path_str) # insert at index 0 so it occurs early in the list ``` -Then, further down in the {file}`conf.py`, add `sphinx.ext.autodoc` to the list of extensions: +Then, further down in the `conf.py` file, add `sphinx.ext.autodoc` to the list of +extensions: ```{code-block} python -:caption: {file}`conf.py` +:caption: `conf.py` extensions = [ ... @@ -49,7 +59,9 @@ extensions = [ ## Usage -See [Sphinx's `autodoc` instructions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#usage) for details. +See [Sphinx's `autodoc` +instructions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#usage) +for details. ## Known issues and limitations @@ -57,13 +69,20 @@ There are a few issues and limitations that should be taken into consideration. ### Language -The extension's usage is limited to Python code. There are extensions for some other languages but they have not been tested with the Starter Pack, such as [sphinxcontrib-rust](https://sphinxcontrib-rust.readthedocs.io/en/stable/) for Rust. +The extension's usage is limited to Python code. There are extensions for some other +languages but they have not been tested with the Sphinx Stack, such as +[sphinxcontrib-rust](https://sphinxcontrib-rust.readthedocs.io/en/stable/) for Rust. ### Docstring format -The `autodoc` extension pulls the docstrings straight into the the reStructuredText (reST) document, which requires the docstrings to be in reST format. For docstrings in the Numpy or Google style, the [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon) extension can convert the docstrings into reST prior to processing by `autodoc`. +The `autodoc` extension pulls the docstrings straight into the the reStructuredText +(reST) document, which requires the docstrings to be in reST format. For docstrings in +the Numpy or Google style, the +[napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon) +extension can convert the docstrings into reST prior to processing by `autodoc`. -For documentation that is written in MyST Markdown, wrap the `eval-rst` directive around the `autodoc` calls: +For documentation that is written in MyST Markdown, wrap the `eval-rst` directive around +the `autodoc` calls: ````{code-block} md @@ -83,7 +102,7 @@ For documentation that is written in MyST Markdown, wrap the `eval-rst` directiv :header-rows: 1 * - Product - - {file}`conf.py` + - `conf.py` - Raw Doc - Rendered Doc diff --git a/docs/how-to/optional-customisation/redirect-pages.md b/docs/how-to/optional-customisation/redirect-pages.md index 45bfe91..43a1135 100644 --- a/docs/how-to/optional-customisation/redirect-pages.md +++ b/docs/how-to/optional-customisation/redirect-pages.md @@ -5,21 +5,38 @@ myst: relatedlinks: "[sphinx-rerediraffe](https://github.com/jahn-junior/sphinx-rerediraffe)" --- +(how-to-redirect-pages)= + # Redirect pages -If a file in your documentation set is moved, deleted or renamed, it can no longer be found at its original location and users will be shown a 404 Not Found page. This can be frustrating for users. +If a file in your documentation set is moved, deleted or renamed, it can no longer be +found at its original location and users will be shown a 404 Not Found page. This can be +frustrating for users. -To provide a better user experience, it is good practice to set up redirects to point to the new location, new file name, or to an alternative place where the information can be found. With documentation on Read the Docs, you can configure redirects [manually via the admin panel](https://docs.readthedocs.io/en/stable/guides/redirects.html). However, since this must be done separately, configuring redirects in RTD doesn't scale for complex and mature documentation where a lot of redirects must be maintained. +To provide a better user experience, it is good practice to set up redirects to point to +the new location, new file name, or to an alternative place where the information can be +found. With documentation on Read the Docs, you can configure redirects [manually via +the admin panel](https://docs.readthedocs.io/en/stable/guides/redirects.html). However, +since this must be done separately, configuring redirects in RTD doesn't scale for +complex and mature documentation where a lot of redirects must be maintained. -The **best practice** is to define and track redirects in your project source, so that when a file is moved, renamed or deleted, you can create a redirect at the same time. In this way, redirects will always be in place when such changes go live. Redirects can either be **external**, meaning that they point to a URL outside your documentation, or **internal**, where you want to point to a new location within your documentation. +The **best practice** is to define and track redirects in your project source, so that +when a file is moved, renamed or deleted, you can create a redirect at the same time. In +this way, redirects will always be in place when such changes go live. Redirects can +either be **external**, meaning that they point to a URL outside your documentation, or +**internal**, where you want to point to a new location within your documentation. -To enable handling redirects in your project repository, the Starter Pack comes with the sphinx-rerediraffe extension. This extension allows you to store redirects in a separate file, `redirects.txt`. +To enable handling redirects in your project repository, the Sphinx Stack comes with the +sphinx-rerediraffe extension. This extension allows you to store redirects in a separate +file, `redirects.txt`. ## Configure sphinx-rerediraffe -Create a file called `redirects.txt` in the same directory as your `conf.py` file. This file will host all of your redirects. +Create a file called `redirects.txt` in the same directory as your `conf.py` file. This +file will host all of your redirects. -Next, in your `conf.py` file, declare the `rediraffe_redirects` variable and assign it the path of the redirects file you just created relative to `conf.py`: +Next, in your `conf.py` file, declare the `rediraffe_redirects` variable and assign it +the path of the redirects file you just created relative to `conf.py`: ```{code-block} python :caption: conf\.py @@ -52,7 +69,10 @@ path/file-name/ new-path/file-name/ # To move a file path/old-name/ new-path/new-name/ # To move and rename a file ``` -Redirects are relative to the root of the `docs/` directory, so for simplicity, it’s best to put the redirects.txt file in the root directory. This is an [example of a working](https://github.com/canonical/ubuntu-server-documentation/blob/main/docs/redirects.txt) `redirect.txt` file. +Redirects are relative to the root of the `docs/` directory, so for simplicity, it’s +best to put the redirects.txt file in the root directory. This is an [example of a +working](https://github.com/canonical/ubuntu-server-documentation/blob/main/docs/redirects.txt) +`redirect.txt` file. ## Layer redirects diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index 417a276..27507ce 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -6,58 +6,87 @@ Publish on Read the Docs ======================== -Publishing your documentation on Read the Docs makes it available to a wider audience with automatic builds triggered by repository updates. -This guide walks you through the process of setting up your Starter Pack-based project on the Read the Docs platform. +Publishing your documentation on Read the Docs makes it available to a wider audience +with automatic builds triggered by repository updates. This guide walks you through the +process of setting up your Sphinx Stack project on Read the Docs. -For Canonical-specific information on how to set up your documentation on Read the Docs, see the `Read the Docs at Canonical `_ and `How to publish documentation on Read the Docs `_ guides. +For Canonical-specific information on how to set up your documentation on Read the Docs, +see the `Read the Docs at Canonical +`_ and `How to +publish documentation on Read the Docs +`_ guides. -In general, after enabling the Starter Pack for your documentation, follow these steps to build and publish your documentation on Read the Docs: +In general, after enabling the Sphinx Stack for your documentation, follow these steps +to build and publish your documentation on Read the Docs: 1. Make sure your documentation :ref:`builds without errors or warnings `. #. Log into Read the Docs. -#. In your account settings, navigate to :guilabel:`Connected services` and check that your GitHub account is listed. - If it's not listed, add a connection to GitHub. See `How to connect your Read the Docs account to your Git provider`_. -#. Use the `manual import`_ to create a project. -#. Specify the path to the :file:`.readthedocs.yaml` file for your build. - To do this, navigate to :guilabel:`Admin` > :guilabel:`Settings` and specify the path under "Path for ``.readthedocs.yaml``". +#. In your account settings, navigate to :guilabel:`Connected services` and check that + your GitHub account is listed. If it's not listed, add a connection to GitHub. See + `How to connect your Read the Docs account to your Git provider + `__. +#. Use the `manual import `__ to + create a project. +#. Specify the path to the ``.readthedocs.yaml`` file for your build. To do this, + navigate to :guilabel:`Admin` > :guilabel:`Settings` and specify the path under "Path + for ``.readthedocs.yaml``". - For example, if your documentation folder is :file:`docs/`, specify the path as ``docs/.readthedocs.yaml``. -#. Update the relative paths in the :file:`.readthedocs.yaml` file to match the structure of your project. You might need to update the file paths specified in the following fields: + For example, if your documentation is stored in the ``docs/`` directory, specify the + path as ``docs/.readthedocs.yaml``. +#. Update the relative paths in the ``.readthedocs.yaml`` file to match the structure of + your project. You might need to update the file paths specified in the following + fields: * ``job.post_checkout`` * ``sphinx.configuration`` * ``python.install.requirements`` -After this initial setup, your documentation should build successfully if your project is hosted from a public repository. -If you get any errors, check the build log for indications on what the problem is. +After this initial setup, your documentation should build successfully if your project +is hosted from a public repository. If you get any errors, check the build log for +indications on what the problem is. + +If your project was imported from a private repository, your initial build will fail +because Read the Docs won't have access to clone the repository. You need to copy your +project's public key from Read the Docs and add it as a deploy key to the repository, +then re-run the build in Read the Docs. -If your project was imported from a private repository, your initial build will fail because Read the Docs won't have access to clone the repository. -You need to copy your project's public key from Read the Docs and add it as a deploy key to the repository, then re-run the build in Read the Docs. Configure the webhook --------------------- -If you have administrator privileges for the GitHub repository that you are adding, the integration webhook (which is responsible for automatically building the documentation when the repository changes) is created automatically. +If you have administrator privileges for the GitHub repository that you are adding, the +integration webhook (which is responsible for automatically building the documentation +when the repository changes) is created automatically. + +If you don't have administrator privileges, the webhook must be set up by someone who +does. The person with administrator privileges must have connected their Read the Docs +account to GitHub. See `How to connect your Read the Docs account to your Git provider +`__. -If you don't have administrator privileges, the webhook must be set up by someone who does. -The person with administrator privileges must have connected their Read the Docs account to GitHub. -See `How to connect your Read the Docs account to your Git provider`_. +See `How to manually configure a Git repository integration +`__ if +you want to set up the +webhook manually. -See `How to manually configure a Git repository integration`_ if you want to set up the webhook manually. Make your documentation public ------------------------------ By default, Read the Docs publishes your documentation for logged-in users only. -To make the documentation public, you must configure the privacy level for each version of the documentation separately. -You can do this by navigating to the :guilabel:`Versions` tab and changing the :guilabel:`Privacy Level` for each version. +To make the documentation public, you must configure the privacy level for each version +of the documentation separately. You can do this by navigating to the +:guilabel:`Versions` tab and changing the :guilabel:`Privacy Level` for each version. + Enable PR previews ------------------ -To make Read the Docs automatically build your documentation when a pull request is opened or updated on GitHub, enable PR reviews for your project. +To make Read the Docs automatically build your documentation when a pull request is +opened or updated on GitHub, enable PR reviews for your project. -To do so, navigate to :guilabel:`Admin` > :guilabel:`Settings` and select :guilabel:`Build pull requests for this project`. +To do so, navigate to :guilabel:`Admin` > :guilabel:`Settings` and select +:guilabel:`Build pull requests for this project`. -Read the Docs will then automatically build the documentation for each pull request, and the link to the output will be available as one of the checks in the pull request. +Read the Docs will then automatically build the documentation for each pull request, and +the link to the output will be available as one of the checks in the pull request. diff --git a/docs/how-to/run-documentation-checks.rst b/docs/how-to/run-documentation-checks.rst index 7515e46..08dfb5f 100644 --- a/docs/how-to/run-documentation-checks.rst +++ b/docs/how-to/run-documentation-checks.rst @@ -1,10 +1,13 @@ +.. meta:: + :description: How to verify your documentation's spelling, links, and language with built-in checks. + .. _run-documentation-checks : Run documentation checks ======================== -The starter pack comes with several tests and checks that you can (and should!) run on your documentation before committing and pushing changes: - +The Sphinx Stack comes with several tests and checks that you can (and should!) run on +your documentation before committing and pushing changes: - :ref:`accessibility_check` - :ref:`inclusive_lang_check` @@ -19,75 +22,100 @@ The starter pack comes with several tests and checks that you can (and should!) Accessibility check ------------------- -The Starter Pack checks the accessibility of the documentation with `Pa11y`_. It's configured to check for Level AA conformity to the `Web Content Accessibility Guidelines (WCAG) 2.2`_. +The Sphinx Stack checks the accessibility of the documentation with `Pa11y +`__. It's +configured to check for Level AA conformity to the `Web Content Accessibility Guidelines +(WCAG) 2.2 `__. -This check is only available locally; it is not part of the Starter Pack's :ref:`github-workflows`. +This check is only available locally; it is not part of the :ref:`github-workflows` in +the Sphinx Stack. -To run the check, you must have ``npm`` and ``Pa11y`` installed. To install ``npm``, refer to the `installation guide `__ for details. Then: +To run the check, you must have ``npm`` and ``Pa11y`` installed. To install ``npm``, +refer to the `installation guide +`__ for details. +Then: .. code-block:: bash npm install pa11y -To check the accessibility of the documentation, run the following command from within your ``/docs`` directory: +To check the accessibility of the documentation, run the following command in your +``/docs`` directory: .. code-block:: bash make pa11y + Configure ~~~~~~~~~ -The ``pa11y.json`` file in the ``.sphinx`` directory provides basic defaults expected to be used for all teams; refrain from removing any unless absolutely necessary. Additional settings and options are detailed in the ``Pa11y`` `README `__ on GitHub. +The ``pa11y.json`` file in the ``_dev`` directory provides basic defaults expected to be +used for all teams; refrain from removing any unless absolutely necessary. Additional +settings and options are detailed in the ``Pa11y`` `README +`__ on GitHub. + .. _inclusive_lang_check: Inclusive language check ------------------------ -The Starter Pack checks for inclusive language with a custom set of `Vale`_ rules. To check for inclusive language violations, run: +The Sphinx Stack checks for inclusive language with a custom set of `Vale +`__ rules. To check for inclusive language violations, run: .. code-block:: bash make woke + Configure ~~~~~~~~~ -If you need to exempt single words or sections, follow the process in :ref:`vale_exemptions`. +If you need to exempt single words or sections, follow the process in +:ref:`vale_exemptions`. + .. _link_check: Link check ---------- -The Starter Pack checks any links in your documentation with the Sphinx ``linkcheck`` builder. To validate the links, run: +The Sphinx Stack checks any links in your documentation with the Sphinx ``linkcheck`` +builder. To validate the links, run: .. code-block:: bash make linkcheck + Configure ~~~~~~~~~ -If you have links in the documentation that you don't want to check, add them to the ``linkcheck_ignore`` list in the ``conf.py`` file. +If you have links in the documentation that you don't want to check, add them to the +``linkcheck_ignore`` list in the ``conf.py`` file. + .. _markdown_lint_check: Markdown lint check ------------------- -The Starter Pack checks standards and consistency in Markdown files with the Markdown lint check. To check your Markdown files, run: +The Sphinx Stack checks standards and consistency in Markdown files with the Markdown +lint check. To check your Markdown files, run: .. code-block:: bash make lint-md + Configure ~~~~~~~~~ -You can update the linting rules in the ``.sphinx/.pymarkdown.json`` file. Refer to `the pymarkdown rules documentation `_ for all the available rules. +You can update the linting rules in the ``_dev/.pymarkdown.json`` file. Refer to `the +pymarkdown rules documentation `_ +for all the available rules. .. _spelling_check: @@ -95,47 +123,60 @@ You can update the linting rules in the ``.sphinx/.pymarkdown.json`` file. Refer Spelling check -------------- -The Starter Pack uses `Vale`_ to check the spelling in your documentation. It ignores inline code, code blocks, and URLs, but it does check the link text. To ensure there are no spelling errors in your documentation, run: +The Sphinx Stack uses `Vale `__ to check the spelling in your +documentation. It ignores inline code, code blocks, and URLs, but it does check the link +text. To ensure there are no spelling errors in your documentation, run: .. code-block:: bash make spelling + Configure ~~~~~~~~~ -If you need to exempt single words or sections, follow the process in :ref:`vale_exemptions`. +If you need to exempt single words or sections, follow the process in +:ref:`vale_exemptions`. + .. _style_guide_linting: Style guide linting ------------------- -The Starter Pack runs the `Vale`_ documentation linter configured with the rules of `style guide `__ To check your documentation with Vale, run: +The Sphinx Stack runs the `Vale `__ documentation linter configured +with the rules of `style guide +`__ To check your documentation +with Vale, run: .. code-block:: bash make vale -Vale can run against individual files, directories, or globs. To check a specific target, run: +Vale can run against individual files, directories, or globs. To check a specific +target, run: .. code-block:: bash make vale TARGET=example.file make vale TARGET=example-directory -If you run the linter against a directory, its subdirectories ware also linted. +If you run the linter against a directory, its subdirectories were also linted. -You can use wildcards to lint globs of files. For example, to run against all Markdown files within a directory, you'd run: +You can use wildcards to lint globs of files. For example, to run against all Markdown +files within a directory, you'd run: .. code-block:: bash make vale TARGET=*.md + Configure ~~~~~~~~~ -If you need to exempt single words or sections, follow the process in :ref:`vale_exemptions`. +If you need to exempt single words or sections, follow the process in +:ref:`vale_exemptions`. + .. _vale_exemptions: .. _reference-automatic-checks-spelling-vale-ignore: @@ -143,12 +184,19 @@ If you need to exempt single words or sections, follow the process in :ref:`vale Vale exemptions --------------- -The :ref:`inclusive_lang_check`, :ref:`spelling_check`, and :ref:`style_guide_linting` all use `Vale`_. These checks share a common syntax for exemptions and pull from the same ``.custom_wordlist.txt`` file. The style guide repository `includes a common list of words `__ that will be excluded from the checks. +The :ref:`inclusive_lang_check`, :ref:`spelling_check`, and :ref:`style_guide_linting` +all use `Vale `__. These checks share a common syntax for exemptions +and pull from the same ``.custom_wordlist.txt`` file. The style guide repository +`includes a common list of words +`__ +that will be excluded from the checks. + A word ~~~~~~ -To ignore a single instance of a word, wrap it in the ``:vale-ignore:`` role. Ensure your ``conf.py`` file contains the appropriate class association in the ``rst_prolog``: +To ignore a single instance of a word, wrap it in the ``:vale-ignore:`` role. Ensure +your ``conf.py`` file contains the appropriate class association in the ``rst_prolog``: .. code-block:: text @@ -157,14 +205,16 @@ To ignore a single instance of a word, wrap it in the ``:vale-ignore:`` role. En :class: vale-ignore """ -To ignore a word across your documentation, add it to your project's ``.custom_wordlist.txt`` file. +To ignore a word across your documentation, add it to your project's +``.custom_wordlist.txt`` file. -.. note:: +.. admonition:: Case sensitivity + :class: note - Entries in ``.custom-wordlist`` are case-sensitive only when the word is capitalized. For instance: + Entries in ``.custom-wordlist`` are case-sensitive only when the word is capitalized. For instance: - - Adding ``kustom`` will cause all instances of ``Kustom`` and ``kustom`` to be ignored. - - Adding ``Kustom`` will cause only instances of ``Kustom`` to be ignored. + - Adding ``kustom`` will cause all instances of ``Kustom`` and ``kustom`` to be ignored. + - Adding ``Kustom`` will cause only instances of ``Kustom`` to be ignored. A section of text @@ -199,7 +249,8 @@ To disable Vale for a section of text, use the following markup: Directives ~~~~~~~~~~ -To disable Vale linting for Directives as a code block or admonitions, apply the `vale-ignore` class to the section: +To disable Vale linting for Directives as a code block or admonitions, apply the +``vale-ignore`` class to the section: .. tab-set:: @@ -223,10 +274,17 @@ To disable Vale linting for Directives as a code block or admonitions, apply the This content will be ignored by Vale. -The class process isn't be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. Also, the `.. class::` directive for reST does not need to encapsulate content, it applies to the next logical block (which can be another directive or even a paragraph of content). The class option should only be used when other options aren't suitable. +The class process isn't be necessary for Markdown, as Vale has an expanded scope for +ignoring Markdown content by default. Also, the `.. class::` directive for reST does not +need to encapsulate content, it applies to the next logical block (which can be another +directive or even a paragraph of content). The class option should only be used when +other options aren't suitable. -.. note:: +.. admonition:: Hyphens and spaces + :class: note The checks may flag terms that contain hyphens or spaces. - For example, "Juju 3" wasn't ignored by default, and `needed to be added to be excepted with an upstream rule `_. + For example, "Juju 3" wasn't ignored by default, and `needed to be added to be + excepted with an upstream rule + `_. diff --git a/docs/how-to/troubleshooting.rst b/docs/how-to/troubleshooting.rst index bb91c07..ae6fc45 100644 --- a/docs/how-to/troubleshooting.rst +++ b/docs/how-to/troubleshooting.rst @@ -1,12 +1,12 @@ .. meta:: - :description: How to troubleshoot common issues with the Sphinx Starter Pack and Read the Docs. + :description: How to troubleshoot common issues with the Sphinx Stack and Read the Docs. .. _troubleshooting: Troubleshooting =================== -This page provides guidance to resolve issues with the Starter Pack and Read the Docs +This page provides guidance to resolve issues with the Sphinx Stack and Read the Docs that are difficult to identify or that we don't expect to be solved. @@ -45,6 +45,7 @@ GitHub page is a 404, then your project has a zombie version. .. image:: ../how-to/assets/troubleshoot-stable-zombie-version.png + Resolution ~~~~~~~~~~ diff --git a/docs/how-to/update-sphinx-stack/index.rst b/docs/how-to/update-sphinx-stack/index.rst new file mode 100644 index 0000000..7cb585f --- /dev/null +++ b/docs/how-to/update-sphinx-stack/index.rst @@ -0,0 +1,55 @@ +.. meta:: + :description: Learn how to update your Sphinx Stack with the latest features and improvements. + +.. _update-sphinx-stacks: + +Update your Sphinx Stack +======================== + +The Sphinx Stack is updated frequently. After you copy its code and it becomes the +documentation system in your project, you must manually maintain it. + +There are special pathways to bring in the latest features and improvements from the +Sphinx Stack repository. + + +Determine your current version +------------------------------ + +There are two versions of the Sphinx Stack that entail different update processes: + +- the **new**, or **extension-based** Sphinx Stack +- the **legacy**, or **pre-extension** Sphinx Stack + + +New Sphinx Stack +^^^^^^^^^^^^^^^^ + +If your ``conf.py`` file includes ``canonical-sphinx`` under the ``extensions`` list, +you are using the new Sphinx Stack. + +To update a new Sphinx Stack project to the latest version, see: + +- :ref:`update-new-sphinx-stack` + +.. note:: + + New Sphinx Stack releases use a semantic versioning scheme for minor and patch + versions, which can be found in your project's ``_dev/version`` file. + + +Legacy Sphinx Stack +^^^^^^^^^^^^^^^^^^^^ + +If your ``conf.py`` file does _not_ include ``canonical-sphinx`` you are using the +legacy Sphinx Stack. + +To update a legacy Sphinx Stack project to the latest version of the new Sphinx Stack: + +- :ref:`update-legacy-sphinx-stack` + +.. toctree:: + :hidden: + + New Sphinx Stack + Legacy Sphinx Stack diff --git a/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst new file mode 100644 index 0000000..b7b3922 --- /dev/null +++ b/docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst @@ -0,0 +1,257 @@ +.. meta:: + :description: Learn how to update Sphinx Stack projects that don't yet use the canonical-sphinx extension. + +.. _update-legacy-sphinx-stack: + +Update the legacy Sphinx Stack +============================== + +This guide outlines the steps required to migrate a documentation project from the +legacy Sphinx Stack (*pre-extension* version) to the latest version that adopts the +``canonical-sphinx`` Sphinx extension. + +The extension-based Sphinx Stack provides a set of features and configurations that are +common across Canonical documentation projects. Key components, such as configuration +and styling, are loaded as an add-on to your project. It can significantly reduce +maintenance concerns when managing your documentation. + +.. note:: + + If ``canonical-sphinx`` is included under ``extensions`` in your ``conf.py`` file, + you are already using an extension-based Sphinx Stack. Follow the guide on + :ref:`updating the new Sphinx Stack `. + + +Update to the last pre-extension version +---------------------------------------- + +Update your documentation project to use the last pre-extension version of the Sphinx +Stack. Doing so will minimize the changes required during the migration by including the +the latest features and configurations available in the pre-extension version. + +In your project repository, check out the `pre-extension release tag +`_: + +.. code-block:: bash + + git checkout tags/pre-extension + +.. admonition:: Repository in detached HEAD state + :class: note + + Checking out a tag leaves your repository in a `detached HEAD state + `_. Before proceeding, create + a new branch: + + .. code-block:: bash + + git checkout -b migrate-to-extension + + +Set up a new project +-------------------- + +#. Back up all existing files in your original documentation project. For example, you + can rename the original ``docs/`` directory to ``docs_backup/``. + + .. warning:: + + If you proceed in the same directory, the following steps will overwrite some of + the configuration files in the original project. +#. Follow the steps in the :ref:`initial-setup` guide to initialise an empty project + with the extension-based Sphinx Stack, at the original file path. +#. Ensure the following files are at the root of your repository: + + - ``.github/workflows/*`` +#. Ensure the following files are moved to their original paths in the project. These + files are defaulted to the repository root, but may have be changed upon project + needs: + + - ``.gitignore`` + - ``.readthedocs.yml`` +#. Validate the project setup locally by running ``make run`` in the new project + directory. + + +Migrate source files +-------------------- + +The Sphinx Stack has undergone breaking changes with the introduction of the +``canonical-sphinx`` extension. This section guides you through: + +- Configuration file changes +- Extension dependencies +- Documentation source migration + +For a complete list of the structural changes, refer to the +`directory-structure-change`_ section. + + +Sphinx configuration +~~~~~~~~~~~~~~~~~~~~~ + +A significant change in the new Sphinx Stack is the organisation of the configuration +files, summarised in the following table: + +.. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Configuration file + - Pre-extension + - Extension-based + * - ``conf.py`` + - Common configurations shared by all Sphinx Stack projects + - Project-specific configurations + * - ``custom_conf.py`` + - Project-specific configuration + - Merged into ``conf.py`` and removed + +In the new Sphinx Stack, many common configurations are provided by the extension and +are loaded automatically when building the documentation. ``docs/conf.py`` is the only +configuration file, and it contains all project-specific configuration. Sensible +defaults are set for general configuration by inclusion of the ``canonical-sphinx`` +extension. + +Ensure that all the previous changes in the original ``custom_conf.py`` file are copied +to the new ``conf.py`` file. + + +Dependencies +~~~~~~~~~~~~ + +If your project requires additional extensions beyond the default list, add the +extension list to the new project in ``docs/requirements.txt``. + + +Documentation source files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Copy all documentation source files from your original project to the new project, + keeping their original structure. These file may include but are not limited to: + + - ``.md`` + - ``.rst`` + - ``.txt`` + - ``.json`` + - images + - scripts +#. Validate the migration by running ``make run``. + + +Apply customisation +------------------- + +If your projects have custom configurations or styles, ensure that you identify and +apply these changes to the new documentation project. + +For general information on customising the extension configuration, see +:ref:`configure-your-project`. + + +Static resources +~~~~~~~~~~~~~~~~ + +The extension provides a set of static resources, such as images, fonts, CSS files, and +HTML templates, that are used to style the documentation for Canonical-branded design. +These resources are bundled with the extension and are no longer provided as source +files in the new Sphinx Stack. + +If you have customised any of these resources in the original project, you need to +manually migrate these changes to the new project. + +For example, if you added customised styling in the original +``.sphinx/_static/custom.css`` file, follow the steps: + +#. Compare the changes between your customised file and the `default CSS file provided + by the extension + `_. + This comparison helps you identify the changes that need to be migrated to the new + project. +#. Create a new CSS file under ``docs/_dev/_static``. You can choose any other file + location in the project directory, but it's recommended to keep the file structure + similar to the original project. +#. Copy the additions and changes to the new empty file. +#. In the ``conf.py``, add the new files into the pre-defined ``html_css_files`` list + variable to overwrite the default settings. +#. Build the documentation to verify that the customised styling is applied correctly. + + +.. _directory-structure-change: + +Directory structure changes +---------------------------- + +After you migrate to the extension, some directories and files are either deleted from +the project or moved to a new location. + +Assuming that all previous documentation files were in the ``docs/`` sub-directory, the +following list illustrates the changes in the directory structure after the migration. + +.. code-block:: text + + . + ├── .github + │ └── workflows + │ ├── automatic-doc-checks.yml + │ └── markdown-style-checks.yml + ├── .sphinx # renamed to `docs/_dev` + │ ├── fonts # removed, files are part of the extension + │ │ ├── Ubuntu-B.ttf + │ │ ├── ubuntu-font-licence-1.0.txt + │ │ ├── UbuntuMono-B.ttf + │ │ ├── UbuntuMono-RI.ttf + │ │ ├── UbuntuMono-R.ttf + │ │ ├── Ubuntu-RI.ttf + │ │ └── Ubuntu-R.ttf + │ ├── images # removed, files are part of the extension + │ │ ├── Canonical-logo-4x.png + │ │ ├── front-page-light.pdf + │ │ ├── front-page.png + │ │ └── normal-page-footer.pdf + │ ├── _static # removed, files are part of the extension + │ │ ├── 404.svg + │ │ ├── custom.css + │ │ ├── favicon.png + │ │ ├── footer.css + │ │ ├── footer.js + │ │ ├── furo_colors.css + │ │ ├── github_issue_links.css + │ │ ├── github_issue_links.js + │ │ ├── header.css + │ │ ├── header-nav.js + │ │ └── tag.png + ├── _templates # moved to `docs/_templates` + │ ├── sidebar # removed + │ │ └── search.html + │ ├── 404.html # removed + │ ├── base.html # removed + │ ├── footer.html + │ ├── header.html + │ └── page.html # removed + │ ├── build_requirements.py # removed + │ ├── get_vale_conf.py + │ ├── latex_elements_template.txt # removed, now part of the extension + │ ├── pa11y-ci.json # renamed to `pa11y.json` + │ └── spellingcheck.yaml + ├── metrics # removed + │ └── scripts + │ ├── build_metrics.sh + │ └── source_metrics.sh + ├── reuse # removed + │ └── links.txt + ├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt` + ├── .gitignore + ├── .readthedocs.yaml + ├── .wordlist.txt # removed + ├── .wokeignore # removed, check replaced by Vale + ├── conf.py # removed, now part of the extension + ├── custom_conf.py # renamed and moved to `docs/conf.py` + ├── doc-cheat-sheet-myst.md # removed + ├── doc-cheat-sheet.rst # removed + ├── index.rst # moved to `docs/index.rst` + ├── init.sh # removed + ├── make.bat # removed + ├── Makefile # moved to `docs/Makefile` + ├── Makefile.sp # removed + └── readme.rst # renamed to `README.md` diff --git a/docs/how-to/update-sphinx-stack/new-sphinx-stack.rst b/docs/how-to/update-sphinx-stack/new-sphinx-stack.rst new file mode 100644 index 0000000..442f3f9 --- /dev/null +++ b/docs/how-to/update-sphinx-stack/new-sphinx-stack.rst @@ -0,0 +1,175 @@ +.. meta:: + :description: Learn how to update Sphinx Stack projects that use the canonical-sphinx extension. + +.. _update-new-sphinx-stack: + +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 + :ref:`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: + +.. code-block:: + + 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: + +.. code-block:: bash + + 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`` diff --git a/docs/how-to/update-starter-packs/index.rst b/docs/how-to/update-starter-packs/index.rst deleted file mode 100644 index c1c785f..0000000 --- a/docs/how-to/update-starter-packs/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. meta:: - :description: Learn how to update your Sphinx Starter Pack with the latest features and improvements. - -.. _update-starter-packs: - -======================== -Update your Starter Pack -======================== - -The Starter Pack is updated frequently. After you copy its code and it becomes the documentation system in your project, you must manually maintain it. - -There are special pathways to bring in the latest features and improvements from the Starter Pack repository. - -Determine your current version ------------------------------- - -There are two versions of the Starter Pack that entail different update processes: - -- the **new**, or **extension-based** Starter Pack -- the **legacy**, or **pre-extension** Starter Pack - -New Starter Pack -^^^^^^^^^^^^^^^^^ - -If your :file:`conf.py` includes ``canonical-sphinx`` under the ``extensions`` list, you are using the new Starter Pack. - -To update a new Starter Pack project to the latest version, see: - -- :ref:`update-new-starter-pack` - -.. note:: - New Starter Pack releases use a semantic versioning scheme for minor and patch versions, which can be found in your project's :file:`.sphinx/version` file. - -Legacy Starter Pack -^^^^^^^^^^^^^^^^^^^^ - -If your :file:`conf.py` does _not_ include ``canonical-sphinx`` you are using the legacy Starter Pack. - -To update a legacy Starter Pack project to the latest version of the new Starter Pack: - -- :ref:`update-legacy-starter-pack` - -.. toctree:: - :hidden: - - New Starter Pack - Legacy Starter Pack diff --git a/docs/how-to/update-starter-packs/legacy-starter-pack.rst b/docs/how-to/update-starter-packs/legacy-starter-pack.rst deleted file mode 100644 index 07a299b..0000000 --- a/docs/how-to/update-starter-packs/legacy-starter-pack.rst +++ /dev/null @@ -1,216 +0,0 @@ -.. meta:: - :description: Learn how to update Sphinx Starter Pack projects that don't yet use the canonical-sphinx extension. - -.. _update-legacy-starter-pack: - -Update the legacy Starter Pack -============================== - -This guide outlines the steps required to migrate a documentation project from the legacy Sphinx Documentation Starter Pack (*pre-extension* version) to the latest version that adopts the ``canonical-sphinx`` Sphinx extension. - -The extension-based documentation Starter Pack provides a set of features and configurations that are common across Canonical documentation projects. Key components, such as configuration and styling, are loaded as an add-on to your project. It can significantly reduce maintenance concerns when managing your documentation. - -.. note:: - If ``canonical-sphinx`` is included under ``extensions`` in your `conf.py`, - you are already using an extension-based starter-pack. Follow the guide on - :ref:`updating the new Starter Pack `. - -Update to the last pre-extension version ----------------------------------------- - -Update your documentation project to use the last pre-extension version of the Sphinx Documentation Starter Pack. Doing so will minimize the changes required during the migration by including the the latest features and configurations available in the pre-extension version. - -In your project repository, check out the `pre-extension release tag `_: - -.. code-block:: bash - - git checkout tags/pre-extension - -.. admonition:: Repository in detached HEAD state - :class: note - - Checking out a tag leaves your repository in a `detached HEAD state `_. Before proceeding, create a new branch: - - .. code-block:: bash - - git checkout -b migrate-to-extension - - -Set up a new project --------------------- - -1. Back up all existing files in your original documentation project. For example, you can rename the original ``docs/`` folder to ``docs_backup/``. - - .. warning:: - - If you proceed in the same directory, the following steps will overwrite some of the configuration files in the original project. - -2. Follow the steps in the :ref:`initial-setup` guide to initialise an empty project with the extension-based Starter Pack, at the original file path. - -3. Ensure the following files are at the root of your repository: - - - ``.github/workflows/*`` - -4. Ensure the following files are moved to their original paths in the project. These files are defaulted to the repository root, but may have be changed upon project needs: - - - ``.gitignore`` - - ``.readthedocs.yml`` - -5. Validate the project setup locally by running ``make run`` in the new project directory. - - -Migrate source files --------------------- - -The documentation Starter Pack has undergone breaking changes with the introduction of the ``canonical-sphinx`` extension. This section guides you through: - -- Configuration file changes -- Extension dependencies -- Documentation source migration - -For a complete list of the structural changes, refer to the `directory-structure-change`_ section. - -Sphinx configuration -~~~~~~~~~~~~~~~~~~~~~ - -A significant change in the new Starter Pack is the organisation of the configuration files, summarised in the following table: - -.. list-table:: - :widths: 20 40 40 - :header-rows: 1 - - * - Configuration file - - Pre-extension - - Extension-based - * - ``conf.py`` - - Common configurations shared by all Starter Pack projects - - Project-specific configurations - * - ``custom_conf.py`` - - Project-specific configuration - - Merged into ``conf.py`` and removed - -In the new Starter Pack, many common configurations are provided by the extension and are loaded automatically when building the documentation. ``docs/conf.py`` is the only configuration file, and it contains all project-specific configuration. Sensible defaults are set for general configuration by inclusion of the `canonical-sphinx` extension. - -Ensure that all the previous changes in the original ``custom_conf.py`` file are copied to the new ``conf.py`` file. - -Dependencies -~~~~~~~~~~~~ - -If your project requires additional extensions beyond the default list, add the extension list to the new project in ``docs/requirements.txt``. - -Documentation source files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Remove the Starter Pack's documentation files (``index.rst`` and any files in the ``docs/**/*`` sub-directory). - -2. Copy all documentation source files from your original project to the new project, keeping their original structure. These file may include but are not limited to: - - - ``.md`` - - ``.rst`` - - ``.txt`` - - ``.json`` - - images - - scripts - -3. Validate the migration by running ``make run``. - -Apply customisation -------------------- - -If your projects have custom configurations or styles, ensure that you identify and apply these changes to the new documentation project. - -For general information on customising the extension configuration, see :ref:`configure-your-project`. - -Static resources -~~~~~~~~~~~~~~~~ - -The extension provides a set of static resources, such as images, fonts, CSS files, and HTML templates, that are used to style the documentation for Canonical-branded design. These resources are bundled with the extension and are no longer provided as source files in the new Starter Pack. - -If you have customised any of these resources in the original project, you need to manually migrate these changes to the new project. - -For example, if you added customised styling in the original ``.sphinx/_static/custom.css`` file, follow the steps: - -1. Compare the changes between your customised file and the `default CSS file provided by the extension `_. This comparison helps you identify the changes that need to be migrated to the new project. -2. Create a new CSS file under ``docs/.sphinx/_static``. You can choose any other file location in the project directory, but it's recommended to keep the file structure similar to the original project. -3. Copy the additions and changes to the new empty file. -4. In the ``conf.py``, add the new files into the pre-defined ``html_css_files`` list variable to overwrite the default settings. -5. Build the documentation to verify that the customised styling is applied correctly. - - -.. _directory-structure-change: - -Directory structure changes ----------------------------- - -After you migrate to the extension, some directories and files are either deleted from the project or moved to a new location. - -Assuming that all previous documentation files were in the ``docs/`` sub-directory, the following list illustrates the changes in the directory structure after the migration. - -.. code-block:: text - - . - ├── .github - │ └── workflows - │ ├── automatic-doc-checks.yml - │ └── markdown-style-checks.yml - ├── .sphinx # moved to `docs/.sphinx` - │ ├── fonts # removed, files are part of the extension - │ │ ├── Ubuntu-B.ttf - │ │ ├── ubuntu-font-licence-1.0.txt - │ │ ├── UbuntuMono-B.ttf - │ │ ├── UbuntuMono-RI.ttf - │ │ ├── UbuntuMono-R.ttf - │ │ ├── Ubuntu-RI.ttf - │ │ └── Ubuntu-R.ttf - │ ├── images # removed, files are part of the extension - │ │ ├── Canonical-logo-4x.png - │ │ ├── front-page-light.pdf - │ │ ├── front-page.png - │ │ └── normal-page-footer.pdf - │ ├── _static # removed, files are part of the extension - │ │ ├── 404.svg - │ │ ├── custom.css - │ │ ├── favicon.png - │ │ ├── footer.css - │ │ ├── footer.js - │ │ ├── furo_colors.css - │ │ ├── github_issue_links.css - │ │ ├── github_issue_links.js - │ │ ├── header.css - │ │ ├── header-nav.js - │ │ └── tag.png - │ ├── _templates # removed, files are part of the extension - │ │ ├── sidebar - │ │ │ └── search.html - │ │ ├── 404.html - │ │ ├── base.html - │ │ ├── footer.html - │ │ ├── header.html - │ │ └── page.html - │ ├── build_requirements.py # removed - │ ├── get_vale_conf.py - │ ├── latex_elements_template.txt # removed, now part of the extension - │ ├── pa11y-ci.json # renamed to `pa11y.json` - │ └── spellingcheck.yaml - ├── metrics # removed - │ └── scripts - │ ├── build_metrics.sh - │ └── source_metrics.sh - ├── reuse # moved to `docs/reuse` - │ └── links.txt - ├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt` - ├── .gitignore - ├── .readthedocs.yaml - ├── .wordlist.txt # moved to `docs/.sphinx/.wordlist.txt` - ├── .wokeignore # removed, check replaced by Vale - ├── conf.py # removed, now part of the extension - ├── custom_conf.py # renamed and moved to `docs/conf.py` - ├── doc-cheat-sheet-myst.md # moved to `docs/doc-cheat-sheet-myst.md` - ├── doc-cheat-sheet.rst # moved to `docs/doc-cheat-sheet.rst` - ├── index.rst # moved to `docs/index.rst` - ├── init.sh # removed - ├── make.bat # removed - ├── Makefile # moved to `docs/Makefile` - ├── Makefile.sp # removed - └── readme.rst # renamed to `README.rst` - diff --git a/docs/how-to/update-starter-packs/new-starter-pack.rst b/docs/how-to/update-starter-packs/new-starter-pack.rst deleted file mode 100644 index 7f1e042..0000000 --- a/docs/how-to/update-starter-packs/new-starter-pack.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. meta:: - :description: Learn how to update Sphinx Starter Pack projects that use the canonical-sphinx extension. - -.. _update-new-starter-pack: - -Update the new Starter Pack -=========================== - -The documentation Starter Pack 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 Starter Pack -- Compare key files and directories in the Starter Pack 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 the Starter Pack's. 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``, - your project is not on an extension-based starter-pack. Follow the guide on - :ref:`updating a legacy Starter Pack project `. - -Clone the Starter Pack repository ---------------------------------- -If you don't have a clean, local copy of the Starter Pack, clone it: - -.. code-block:: - - git clone https://github.com/canonical/sphinx-docs-starter-pack.git - -Confirm that both the Starter Pack's 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 Starter Pack versions often change the default configuration files. You'll -need to merge your project files with the config files from the new Starter Pack. -The recommended approach is to copy the customizations in your project to the starter -pack's config files and then replace your project's config files with the starter -pack's. - -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 Starter Pack's -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 ``/.sphinx`` 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 Starter Pack, 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 ``.sphinx`` directory --------------------------------- -In addition to the docs above, the ``/.sphinx`` 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 ``/.sphinx`` directory and replace it with the Starter Pack's. If there -are modifications in your project's ``/.sphinx`` directory, it is recommended that -they transfer them out. - -Review the remaining files --------------------------- -Some files in the Starter Pack 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, e.g., ``sphinxext-rediraffe`` if you use rediraffe to - handle redirects. - -- Review the workflows in the ``/.github`` directory: If there are changes in the - following workflows, replace the existing files with the new ones. The starter - pack 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 starter-pack -specific 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 Starter Pack-specific 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-starter-pack.yml`` - -- These files can be deleted as long as they are not being used in your docs: - - - ``docs/reuse/links.txt`` - - ``docs/reuse/mermaid.txt`` - - ``docs/reuse/substitutions.txt`` - - ``docs/reuse/substitutions.yaml`` diff --git a/docs/index.rst b/docs/index.rst index 36a9737..2f44570 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,11 @@ -Sphinx Starter Pack documentation -================================= +Sphinx Stack documentation +========================== -The documentation Starter Pack helps you to quickly set up, build, and publish -documentation with Sphinx. +The Sphinx Stack helps you set up, build, and publish documentation with Sphinx. -It contains common styling and configuration through the `Canonical Sphinx`_ extension, -supports both |RST| and Markdown, and includes automatic documentation checks. +It contains common styling and configuration through the `Canonical Sphinx +`__ extension, supports both |RST| and +Markdown, and includes automatic documentation checks. In this documentation @@ -17,7 +17,7 @@ In this documentation :link: /set-up-a-new-project :link-type: doc - Set up the Sphinx Starter Pack in your project for the first time. + Set up the Sphinx Stack in your project for the first time. .. grid-item-card:: How-to guides :link: /how-to/index @@ -37,13 +37,14 @@ In this documentation :link: /explanation/index :link-type: doc - **Concepts** - understand the design and architecture of the Starter Pack. + **Concepts** - understand the design and architecture of the Sphinx Stack. Project and community ---------------------- -The Canonical Sphinx Starter Pack is an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback. +The Sphinx Stack is an open source project that warmly welcomes community contributions, +suggestions, fixes and constructive feedback. .. toctree:: diff --git a/docs/redirects.txt b/docs/redirects.txt index 3ba6791..24bf9e6 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -18,8 +18,10 @@ "how-to/build/" "how-to/build-and-preview" "how-to/edit/" "set-up-a-new-project" "how-to/guidance/" "how-to" -"how-to/migrate-from-pre-extension" "how-to/update-starter-packs/legacy-starter-pack" -"how-to/update-starter-packs/pre-extension" "how-to/update-starter-packs/legacy-starter-pack" +"how-to/migrate-from-pre-extension" "how-to/update-sphinx-stack/legacy-sphinx-stack" +"how-to/update-starter-packs/pre-extension" "how-to/update-sphinx-stack/legacy-sphinx-stack" +"how-to/update-starter-packs/legacy-starter-pack" "how-to/update-sphinx-stack/legacy-sphinx-stack" +"how-to/update-starter-packs/new-starter-pack" "how-to/update-sphinx-stack/new-sphinx-stack" "how-to/bridge-project-and-doc-builds/" "how-to/optional-customisation/bridge-project-and-docs-builds" "how-to/create-data-tables/" "how-to/optional-customisation/interactive-tables" "how-to/custom-templates/" "how-to/optional-customisation/custom-html-templates" diff --git a/docs/reference/default-extensions.rst b/docs/reference/default-extensions.rst index 0ab8e58..66a18c0 100644 --- a/docs/reference/default-extensions.rst +++ b/docs/reference/default-extensions.rst @@ -1,12 +1,12 @@ .. meta:: - :description: A list of extensions included in the Starter Pack by default. + :description: A list of extensions included in the Sphinx Stack by default. .. _reference-default-sphinx-extensions: Default Sphinx extensions ========================= -These extensions are enabled in the Starter Pack by default. +These extensions are enabled in the Sphinx Stack by default. ``canonical_sphinx`` Contains the default Canonical branded theme. @@ -24,7 +24,7 @@ These extensions are enabled in the Starter Pack by default. Handles URL redirects for moved or deleted pages. Default Support for this extension will be dropped in an upcoming release of the - Starter Pack. Update your documentation to use ``sphinxext-rediraffe`` instead. + Sphinx Stack. Update your documentation to use ``sphinx-rerediraffe`` instead. Needed by ``canonical_sphinx``. @@ -62,6 +62,9 @@ These extensions are enabled in the Starter Pack by default. ``sphinx_last_updated_by_git`` Fetches and displays the accurate 'last updated' date for pages by reading Git commit metadata. +``sphinx_llm.txt`` + Generates Markdown artifacts that improve readability for LLMs. + ``sphinx_related_links`` Generates and injects a list of related links into documentation pages. diff --git a/docs/reference/github-workflows.rst b/docs/reference/github-workflows.rst index 00e4a3e..8694da8 100644 --- a/docs/reference/github-workflows.rst +++ b/docs/reference/github-workflows.rst @@ -1,12 +1,18 @@ +.. meta:: + :description: Reference for the built-in GitHub workflows that check your documentation's spelling, links, and language. + + .. _github-workflows: GitHub workflows ================ -The primary documentation workflow checks spelling, links, and inclusive language in a documentation project; -these are the same checks as described in :ref:`run-documentation-checks`. +The primary documentation workflow checks spelling, links, and inclusive language in a +documentation project; these are the same checks as described in +:ref:`run-documentation-checks`. -The ``documentation-checks.yaml`` workflow covers these three checks and can be added to a new or existing workflow's jobs with: +The ``documentation-checks.yaml`` workflow covers these three checks and can be added to +a new or existing workflow's jobs with: .. code:: yaml @@ -18,8 +24,8 @@ The ``documentation-checks.yaml`` workflow covers these three checks and can be working-directory: 'docs' -Workflows are also available for each individual check so that projects may run a subset of -those defined in ``documentation-checks.yaml``: +Workflows are also available for each individual check so that projects may run a subset +of those defined in ``documentation-checks.yaml``: .. code:: yaml @@ -41,8 +47,9 @@ those defined in ``documentation-checks.yaml``: Input ----- -The table below lists the inputs for the ``documentation-checks.yaml`` workflow. If your project consumes the -Starter Pack in a non-traditional way, declare any of the following inputs to customize the workflow as needed: +The table below lists the inputs for the ``documentation-checks.yaml`` workflow. If your +project consumes the Sphinx Stack in a non-traditional way, declare any of the following +inputs to customize the workflow as needed: .. list-table:: :header-rows: 1 @@ -84,12 +91,12 @@ Check for removed URLs .. versionadded:: 1.2.0 -The Starter Pack includes a GitHub action to identify when pages have been removed. -This includes moving pages to another path, or removing them completely. +The Sphinx Stack includes a GitHub action to identify when pages have been removed. This +includes moving pages to another path, or removing them completely. -This does not cover higher-level changes to URL paths, such as changes to the project name or URL slug pattern on RTD. +This does not cover higher-level changes to URL paths, such as changes to the project +name or URL slug pattern on RTD. -This check ensures that redirects are implemented when pages are moved, or -appropriate information is provided when anything is removed. It only runs -on pull request builds. +This check ensures that redirects are implemented when pages are moved, or appropriate +information is provided when anything is removed. It only runs on pull request builds. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 99a0f4b..3ee94fb 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -2,11 +2,12 @@ Reference ========= Syntax guides, list of enabled sphinx extensions, and reference information -for the Starter Pack's GitHub workflows. +for the Sphinx Stack GitHub workflows. Also see the following information: -- `Sphinx documentation Starter Pack repository`_ +- `Sphinx Stack repository `__ + Contents -------- @@ -18,4 +19,3 @@ Contents default-extensions rst-syntax myst-syntax - diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md index 024a74b..b84313a 100644 --- a/docs/reference/myst-syntax.md +++ b/docs/reference/myst-syntax.md @@ -2,7 +2,7 @@ relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) myst: html_meta: - description: MyST Markdown syntax for use in Starter Pack projects, including headings, links, code blocks, directives, and reusable content patterns. + description: Reference for the MyST syntax conventions used by Canonical. substitutions: advanced_reuse_key: "This is a substitution that includes a code block: ``` @@ -14,16 +14,19 @@ myst: # MyST syntax -The Starter Pack supports [Markdown](https://commonmark.org/) and [MyST](https://myst-parser.readthedocs.io/). +The Sphinx Stack supports [Markdown](https://commonmark.org/) and +[MyST](https://myst-parser.readthedocs.io/). See the following sections for syntax help and conventions. ```{note} -This guide assumes that you are using the [Sphinx documentation Starter Pack](https://github.com/canonical/sphinx-docs-starter-pack). -Some of the mentioned syntax requires Sphinx extensions (which are enabled in the Starter Pack). +This guide assumes that you are using the [Sphinx +Stack](https://github.com/canonical/sphinx-stack). Some of the mentioned syntax requires +Sphinx extensions (which are enabled in the Sphinx Stack). ``` -For general style conventions, see the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en). +For general style conventions, see the [Canonical Documentation Style +Guide](https://docs.ubuntu.com/styleguide/en). ## Headings @@ -76,8 +79,11 @@ Adhere to the following conventions: Adhere to the following conventions: -- Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept). -- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to get your point across. +- Use italics sparingly. Common uses for italics are titles and names (for example, when + referring to a section title that you cannot link to, or when introducing the name for + a concept). +- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to + get your point across. ## Code blocks @@ -85,7 +91,8 @@ Start and end a code block with three back ticks: ``` -You can specify the code language after the back ticks to enforce a specific lexer, but in many cases, the default lexer works just fine. +You can specify the code language after the back ticks to enforce a specific lexer, but +in many cases, the default lexer works just fine. `````{list-table} :header-rows: 1 @@ -252,18 +259,22 @@ To customize the prompt (`user@host:~$` by default), specify any of the followin The copy button for input commands is **opt-in**. You must include the `:copy:` flag in the directive's options for the button to be displayed. -To make the terminal scroll horizontally instead of wrapping long lines, include the `:scroll:` option. +To make the terminal scroll horizontally instead of wrapping long lines, include the +`:scroll:` option. -For more details, refer to the [`sphinx-terminal` README](https://github.com/canonical/sphinx-terminal/blob/main/README.md). +For more details, refer to the [`sphinx-terminal` +README](https://github.com/canonical/sphinx-terminal/blob/main/README.md). ## Links -How to link depends on if you are linking to an external URL or to another page in the documentation. +How to link depends on if you are linking to an external URL or to another page in the +documentation. ### External links -For external links, use Markdown syntax. -You can also use just the URL, but this will usually cause issues with the spelling check, so you should specify the link text as code in this case. +For external links, use Markdown syntax. You can also use just the URL, but this will +usually cause issues with the spelling check, so you should specify the link text as +code in this case. ```{list-table} :header-rows: 1 @@ -298,7 +309,9 @@ To add a link to a related website, add the following field at the top of the pa relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [RTFM](https://www.google.com) -To override the title, use Markdown syntax. Note that spaces are ignored; if you need spaces in the title, replace them with ` `, and include the value in quotes if Sphinx complains about the metadata value because it starts with `[`. +To override the title, use Markdown syntax. Note that spaces are ignored; if you need +spaces in the title, replace them with ` `, and include the value in quotes if +Sphinx complains about the metadata value because it starts with `[`. To add a link to a Discourse topic, configure the Discourse instance in the {file}`conf.py` file. Then add the following field at the top of the page (where `12345` is the ID of the Discourse topic): @@ -333,15 +346,19 @@ To override the title, add the `:title:` option. ### Internal references -For internal references, both Markdown and MyST syntax are supported. In most cases, you should use MyST syntax though, because it resolves the link text automatically and gives an indication of the link in GitHub rendering. +For internal references, both Markdown and MyST syntax are supported. In most cases, you +should use MyST syntax though, because it resolves the link text automatically and gives +an indication of the link in GitHub rendering. (a_section_target_myst)= #### Referencing a section -To reference a section within the documentation (either on the same page or on another page), add a target to that section and reference that target. +To reference a section within the documentation (either on the same page or on another +page), add a target to that section and reference that target. -You can add targets at any place in the documentation. However, if there is no heading or title for the targeted element, you must specify a link text. +You can add targets at any place in the documentation. However, if there is no heading +or title for the targeted element, you must specify a link text. (a_random_target_myst)= @@ -363,7 +380,9 @@ You can add targets at any place in the documentation. However, if there is no h - References a target and specifies a title. * - `` {ref}`project_key:an_external_target` `` - Default link text - - You can also reference targets in other Sphinx projects. `project-key` must be a key in the `intersphinx_mapping` dictionary in `conf.py`. The link text defaults to the target's title. + - You can also reference targets in other Sphinx projects. `project-key` must be a key + in the `intersphinx_mapping` dictionary in `conf.py`. The link text defaults to the + target's title. * - ``[`xyz`](a_random_target_myst)`` - [`xyz`](a_random_target_myst) - Use Markdown syntax if you need markup on the link text. @@ -371,14 +390,19 @@ You can add targets at any place in the documentation. However, if there is no h Adhere to the following conventions: -- Never use external links to reference a section in the same doc set or a doc set that is linked with Intersphinx. It would likely cause a broken link in the future. -- Override the link text only when it is necessary. If you can use the section title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. +- Never use external links to reference a section in the same doc set or a doc set that + is linked with Intersphinx. It would likely cause a broken link in the future. +- Override the link text only when it is necessary. If you can use the section title as + link text, do so, because the text will then update automatically if the title + changes. +- Never "override" the link text with the same text that would be generated + automatically. #### Referencing a page -If a documentation page does not have a target, you can still reference it by using the `{doc}` role with the file name and path. -Use MyST syntax to automatically extract the link text. When overriding the link text, use Markdown syntax. +If a documentation page does not have a target, you can still reference it by using the +`{doc}` role with the file name and path. Use MyST syntax to automatically extract the +link text. When overriding the link text, use Markdown syntax. ```{list-table} :header-rows: 1 @@ -402,15 +426,23 @@ Use MyST syntax to automatically extract the link text. When overriding the link Adhere to the following conventions: -- Only use the `{doc}` role when you cannot use the `{ref}` role, thus only if there is no target at the top of the file and you cannot add it. When using the `{doc}` role, your reference will break when a file is renamed or moved. -- Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. +- Only use the `{doc}` role when you cannot use the `{ref}` role, thus only if there is + no target at the top of the file and you cannot add it. When using the `{doc}` role, + your reference will break when a file is renamed or moved. +- Override the link text only when it is necessary. If you can use the document title as + link text, do so, because the text will then update automatically if the title + changes. +- Never "override" the link text with the same text that would be generated + automatically. ## Navigation -Every documentation page must be included as a sub-page to another page in the navigation. +Every documentation page must be included as a sub-page to another page in the +navigation. -This is achieved with the [`toctree`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directive in the parent page: +This is achieved with the +[`toctree`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) +directive in the parent page: ```` ```{toctree} @@ -421,7 +453,8 @@ sub-page2 ``` ```` -If a page should not be included in the navigation, you can suppress the resulting build warning by putting the following instruction at the top of the file: +If a page should not be included in the navigation, you can suppress the resulting build +warning by putting the following instruction at the top of the file: ``` --- @@ -432,10 +465,12 @@ orphan: true Use orphan pages sparingly and only if there is a clear reason for it. ```{tip} -Instead of hiding pages that you do not want to include in the documentation from the navigation, you can exclude them from being built. -This method will also prevent them from being found through the search. +Instead of hiding pages that you do not want to include in the documentation from the +navigation, you can exclude them from being built. This method will also prevent them +from being found through the search. -To exclude pages from the build, add them to the `custom_excludes` variable in the {file}`conf.py` file. +To exclude pages from the build, add them to the `custom_excludes` variable in the +`conf.py` file. ``` ## Lists @@ -510,8 +545,11 @@ Adhere to the following conventions: ## Tables -You can use standard Markdown tables. However, using the reST [list table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) syntax is usually much easier. -See the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives) for all table syntax alternatives. +You can use standard Markdown tables. However, using the reST [list +table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) syntax +is usually much easier. See the [Sphinx +documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives) +for all table syntax alternatives. Both markups result in the following output: @@ -539,7 +577,9 @@ Both markups result in the following output: ### List tables -See [list tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) for reference. +See [list +tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) for +reference. ```` ```{list-table} @@ -576,8 +616,8 @@ For example: ``` ```` -If you have a large amount of CSV data, or the data is generated by an automated process, -you can include the data from a file. +If you have a large amount of CSV data, or the data is generated by an automated +process, you can include the data from a file. For example: @@ -605,7 +645,7 @@ Both markups result in the following output: Customize the column widths, character encoding, and so on, as described in the [`csv-table` reference](https://mystmd.org/guide/directives#directive-csv-table). -The Starter Pack can also render interactive tables. See: {ref}`interactive-tables`. +The Sphinx Stack can also render interactive tables. See: {ref}`interactive-tables`. ## Notes @@ -685,7 +725,9 @@ Adhere to the following conventions: - For local pictures, start the path with `/` (for example, `/images/image.png`). - Use `PNG` format for screenshots and `SVG` format for graphics. -- See [Five golden rules for compliant alt text](https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text) for information about how to word the alt text. +- See [Five golden rules for compliant alt + text](https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text) + for information about how to word the alt text. ## Reuse @@ -693,50 +735,63 @@ A big advantage of MyST in comparison to plain Markdown is that it allows to reu ### Substitution -To reuse sentences or paragraphs that have little markup and special formatting, use [substitutions](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions). +To reuse sentences or paragraphs that have little markup and special formatting, use +[substitutions](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions). Substitutions can be defined in the following locations: -- Globally, in a file named {file}`reuse/substitutions.yaml` that is loaded into the [`myst_substitutions`](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax-optional.html#substitutions-with-jinja2) variable in {file}`conf.py`: +**Globally**, in a file named {file}`reuse/substitutions.yaml` that is loaded into the +[`myst_substitutions`](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax-optional.html#substitutions-with-jinja2) +variable in `conf.py`. Or if you have a limited amount of substitutions, enter them +directly into the `myst_substitutions` variable in `conf.py`: - ```{code-block} python - :caption: "{spellexception}`conf.py`" +```{code-block} python +:caption: "{spellexception}`conf.py`" - import os - import yaml +import os +import yaml - ... - - if os.path.exists('./reuse/substitutions.yaml'): +if os.path.exists('./reuse/substitutions.yaml'): with open('./reuse/substitutions.yaml', 'r') as fd: myst_substitutions = yaml.safe_load(fd.read()) - ``` - - ```{code-block} yaml - :caption: "{spellexception}`reuse/substitutions.yaml`" - - # Key/value substitutions to use within the Sphinx doc. - {version_number: "0.1.0", - formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} -- Locally, putting the definitions at the top of a single file in the following format: - - ```` - --- - myst: - substitutions: - version_number: "0.1.0" - formatted_text: "*Multi-line* text - that uses basic **markup**." - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" - - --- - ```` - -You can combine both options by defining a default substitution in `reuse/substitutions.py` and overriding it at the top of a file. +else: + myst_substitutions = { + "version_number": "0.1.0", + "formatted_text": "*Multi-line* text\n that uses basic **markup**.", + "site_link": "[Website link](https://example.com)" + } +``` + +```{code-block} yaml +:caption: "{spellexception}`reuse/substitutions.yaml`" + +# Key/value substitutions to use within the Sphinx doc. +{version_number: "0.1.0", + formatted_text: "*Multi-line* text\n that uses basic **markup**.", + site_link: "[Website link](https://example.com)"} + +``` + +**Locally**, putting the definitions at the top of a single file in the following +format: + + +```` +--- +myst: + substitutions: + version_number: "0.1.0" + formatted_text: "*Multi-line* text + that uses basic **markup**." + advanced_reuse_key: "This is a substitution that includes a code block: + ``` + code block + ```" +--- +```` + +You can combine both options by defining a default substitution in +`reuse/substitutions.py` and overriding it at the top of a file. The definitions from the above examples are rendered as follows: @@ -757,17 +812,25 @@ The definitions from the above examples are rendered as follows: Adhere to the following convention: -- Substitutions do not work on GitHub. Therefore, use substitution names that indicate the included content (for example, `note_not_supported` instead of `reuse_note`). +- Substitutions do not work on GitHub. Therefore, use substitution names that indicate + the included content (for example, `note_not_supported` instead of `reuse_note`). ### File inclusion -To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations. +To reuse longer sections or text with more advanced markup, you can put the content in a +separate file and include the file or parts of the file in several locations. -To select parts of the text in a file, use `:start-after:` and `:end-before:` if possible. You can combine those with `:start-line:` and `:end-line:` if required (if the same text occurs more than once). Using only `:start-line:` and `:end-line:` is error-prone though. +To select parts of the text in a file, use `:start-after:` and `:end-before:` if +possible. You can combine those with `:start-line:` and `:end-line:` if required (if the +same text occurs more than once). Using only `:start-line:` and `:end-line:` is +error-prone though. -You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file. +You cannot put any targets into the content that is being reused (because references to +this target would be ambiguous then). You can, however, put a target right before +including the file. -By combining file inclusion and substitutions, you can even replace parts of the included text. +By combining file inclusion and substitutions, you can even replace parts of the +included text. `````{list-table} :header-rows: 1 @@ -796,13 +859,18 @@ By combining file inclusion and substitutions, you can even replace parts of the Adhere to the following convention: -- File inclusion does not work on GitHub. Therefore, always add a comment linking to the included file. -- Files that only contain text that is reused somewhere else should be placed in the {file}`reuse` folder and end with the extension ``.txt`` to distinguish them from normal content files. -- To make sure inclusions don't break, consider adding HTML comments (``) to the source file as markers for starting and ending. +- File inclusion does not work on GitHub. Therefore, always add a comment linking to the + included file. +- Files that only contain text that is reused somewhere else should be placed in the + `reuse` directory and end with the extension ``.txt`` to distinguish them from + normal content files. +- To make sure inclusions don't break, consider adding HTML comments (``) to the source file as markers for starting and ending. ## Tabs -The recommended way of creating tabs is to use the tabs that the [Sphinx design](https://sphinx-design.readthedocs.io/en/latest/) extension provides. +The recommended way of creating tabs is to use the tabs that the [Sphinx +design](https://sphinx-design.readthedocs.io/en/latest/) extension provides. ``````{list-table} :header-rows: 1 @@ -845,7 +913,10 @@ The recommended way of creating tabs is to use the tabs that the [Sphinx design] ```` `````` -Alternatively, you can use the [Sphinx tabs](https://sphinx-tabs.readthedocs.io/en/latest/) extension, which is also enabled by default. This was previously recommended due to limitations in Sphinx Design that are now fixed. +Alternatively, you can use the [Sphinx +tabs](https://sphinx-tabs.readthedocs.io/en/latest/) extension, which is also enabled by +default. This was previously recommended due to limitations in Sphinx Design that are +now fixed. ``````{list-table} :header-rows: 1 @@ -886,7 +957,8 @@ Alternatively, you can use the [Sphinx tabs](https://sphinx-tabs.readthedocs.io/ ## Collapsible sections -There is no support for details sections in MyST, but you can insert HTML to create them. +There is no support for details sections in MyST, but you can insert HTML to create +them. ````{list-table} :header-rows: 1 @@ -911,7 +983,8 @@ There is no support for details sections in MyST, but you can insert HTML to cre ## Glossary -You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file. +You can define glossary terms in any file. Ideally, all terms should be collected in one +glossary file though, and they can then be referenced from any file. `````{list-table} :header-rows: 1 diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index caf801e..da347ec 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -1,5 +1,5 @@ .. meta:: - :description: reStructuredText syntax for use in Starter Pack projects, including headings, links, code blocks, and tables. + :description: Reference for the reStructuredText syntax conventions used by Canonical. :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) @@ -8,15 +8,20 @@ reStructuredText syntax ======================= -The Starter Pack supports `reStructuredText`_ (reST). +The Sphinx Stack supports `reStructuredText +`__ (reST). See the following sections for syntax help and conventions. .. note:: - This guide assumes that you are using the `Sphinx documentation starter pack`_. - Some of the mentioned syntax requires Sphinx extensions (which are enabled in the Starter Pack). -For general style conventions, see the `Canonical Documentation Style Guide`_. + This guide assumes that you are using the `Sphinx Stack + `__. Some of the mentioned syntax + requires Sphinx extensions (which are enabled in the Sphinx Stack). + +For general style conventions, see the `Canonical Documentation Style Guide +`__. + Headings -------- @@ -61,6 +66,7 @@ Adhere to the following conventions: Use the ones specified above. - Use sentence style for headings (capitalise only the first word). + Inline formatting ----------------- @@ -86,18 +92,25 @@ Inline formatting Adhere to the following conventions: -- Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept). -- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to get your point across. +- Use italics sparingly. Common uses for italics are titles and names (for example, when + referring to a section title that you cannot link to, or when introducing the name for + a concept). +- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to + get your point across. + Code blocks ----------- -To start a code block, either end the introductory paragraph with two colons (``::``) and indent the following code block, or explicitly start a code block with ``.. code::``. -In both cases, the code block must be surrounded by empty lines. +To start a code block, either end the introductory paragraph with two colons (``::``) +and indent the following code block, or explicitly start a code block with ``.. +code::``. In both cases, the code block must be surrounded by empty lines. -When explicitly starting a code block, you can specify the code language to enforce a specific lexer, but in many cases, the default lexer works just fine. +When explicitly starting a code block, you can specify the code language to enforce a +specific lexer, but in many cases, the default lexer works just fine. -For a list of supported languages and their respective lexers, see the official `Pygments documentation`_. +For a list of supported languages and their respective lexers, see the official +`Pygments documentation `__. .. list-table:: :header-rows: 1 @@ -139,6 +152,7 @@ For a list of supported languages and their respective lexers, see the official code: - example: true + Terminal output ~~~~~~~~~~~~~~~ @@ -237,6 +251,7 @@ To make the terminal scroll horizontally instead of wrapping long lines, include For more details, refer to the `sphinx-terminal README `_. + Links ----- @@ -244,6 +259,8 @@ Link markup depends on whether you need an external URL or a page in the same documentation set. +.. _reference-external-link-syntax: + External links ~~~~~~~~~~~~~~ @@ -312,7 +329,8 @@ Define the links in a shared file: To keep the text readable and links maintainable, put all link definitions in a file named :file:`reuse/links.txt` to include it in a custom ``rst_epilog`` directive - (see the `Sphinx documentation `_). + (see the `rst_epilog documentation + `__). .. code-block:: python :caption: :spellexception:`conf.py` @@ -330,6 +348,7 @@ Define the links in a shared file: * - ```Canonical website`_`` - `Canonical website`_ + Related links ^^^^^^^^^^^^^ @@ -346,6 +365,7 @@ Then add the following field at the top of the page (where ``12345`` is the ID o :discourse: 12345 + Manual-page links ^^^^^^^^^^^^^^^^^ @@ -391,11 +411,13 @@ To add a link to a YouTube video, use the following directive: The video title is extracted automatically and displayed when hovering over the link. To override the title, add the ``:title:`` option. + Internal references ~~~~~~~~~~~~~~~~~~~ You can reference pages and targets in this documentation set, and also in other documentation sets using Intersphinx. + .. _a_section_target: Referencing a section @@ -435,6 +457,7 @@ Adhere to the following conventions: - Override the link text only when it is necessary. If you can use the referenced title as link text, do so, because the text will then update automatically if the title changes. - Never "override" the link text with the same text that would be generated automatically. + Referencing a page ^^^^^^^^^^^^^^^^^^ @@ -457,17 +480,26 @@ If a documentation page does not have a target, you can still reference it by us Adhere to the following conventions: -- Only use the ``:doc:`` role when you cannot use the ``:ref:`` role, thus only if there is no target at the top of the file and you cannot add it. When using the ``:doc:`` role, your reference will break when a file is renamed or moved. -- Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. -- When using an external target, ``project_key`` must be a key in the ``intersphinx_mapping`` dictionary in ``conf.py``. +- Only use the ``:doc:`` role when you cannot use the ``:ref:`` role, thus only if there + is no target at the top of the file and you cannot add it. When using the ``:doc:`` + role, your reference will break when a file is renamed or moved. +- Override the link text only when it is necessary. If you can use the document title as + link text, do so, because the text will then update automatically if the title + changes. +- Never "override" the link text with the same text that would be generated + automatically. +- When using an external target, ``project_key`` must be a key in the + ``intersphinx_mapping`` dictionary in ``conf.py``. + Navigation ---------- Every documentation page must be included as a sub-page to another page in the navigation. -This is achieved with the `toctree`_ directive in the parent page:: +This is achieved with the `toctree +`__ +directive in the parent page:: .. toctree:: :hidden: @@ -475,76 +507,82 @@ This is achieved with the `toctree`_ directive in the parent page:: sub-page1 sub-page2 -If a page should not be included in the navigation, you can suppress the resulting build warning by putting ``:orphan:`` at the top of the file. -Use orphan pages sparingly and only if there is a clear reason for it. +If a page should not be included in the navigation, you can suppress the resulting build +warning by putting ``:orphan:`` at the top of the file. Use orphan pages sparingly and +only if there is a clear reason for it. .. tip:: - Instead of hiding pages that you do not want to include in the documentation from the navigation, you can exclude them from being built. - This method will also prevent them from being found through the search. - To exclude pages from the build, add them to the ``custom_excludes`` variable in the :file:`conf.py` file. + Instead of hiding pages that you do not want to include in the documentation from + the navigation, you can exclude them from being built. This method will also prevent + them from being found through the search. + + To exclude pages from the build, add them to the ``custom_excludes`` variable in the + ``conf.py`` file. + Lists ----- .. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - - Item 1 - - Item 2 - - Item 3 - - - Item 1 - - Item 2 - - Item 3 - * - .. code:: + :header-rows: 1 - 1. Step 1 - #. Step 2 - #. Step 3 - - 1. Step 1 - #. Step 2 - #. Step 3 - * - .. code:: + * - Input + - Output + * - .. code:: - a. Step 1 - #. Step 2 - #. Step 3 - - a. Step 1 - #. Step 2 - #. Step 3 + - Item 1 + - Item 2 + - Item 3 + - - Item 1 + - Item 2 + - Item 3 + * - .. code:: + + 1. Step 1 + #. Step 2 + #. Step 3 + - 1. Step 1 + #. Step 2 + #. Step 3 + * - .. code:: + + a. Step 1 + #. Step 2 + #. Step 3 + - a. Step 1 + #. Step 2 + #. Step 3 You can also nest lists: .. tab-set:: - .. tab-item:: Input + .. tab-item:: Input - .. code:: + .. code:: - 1. Step 1 + 1. Step 1 - - Item 1 + - Item 1 - * Sub-item - - Item 2 + * Sub-item + - Item 2 - i. Sub-step 1 - #. Sub-step 2 - #. Step 2 + i. Sub-step 1 + #. Sub-step 2 - a. Sub-step 1 + #. Step 2 - - Item - #. Sub-step 2 - .. tab-item:: Output + a. Sub-step 1 + - Item + + #. Sub-step 2 + .. tab-item:: Output - 1. Step 1 + 1. Step 1 - Item 1 @@ -553,96 +591,108 @@ You can also nest lists: i. Sub-step 1 #. Sub-step 2 - #. Step 2 - a. Sub-step 1 + #. Step 2 - - Item - #. Sub-step 2 + a. Sub-step 1 + - Item + #. Sub-step 2 Adhere to the following conventions: -- In numbered lists, number the first item and use ``#.`` for all subsequent items to generate the step numbers automatically. -- Use ``-`` for unordered lists. When using nested lists, you can use ``*`` for the nested level. +- In numbered lists, number the first item and use ``#.`` for all subsequent items to + generate the step numbers automatically. +- Use ``-`` for unordered lists. When using nested lists, you can use ``*`` for the + nested level. + Definition lists ~~~~~~~~~~~~~~~~ .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Input - - Output - * - .. code:: + * - Input + - Output + * - .. code:: + + Term 1: + Definition + Term 2: + Definition + - Term 1: + Definition + Term 2: + Definition - Term 1: - Definition - Term 2: - Definition - - Term 1: - Definition - Term 2: - Definition .. _style-guide-tables: Tables ------ -reST supports different markup for tables. Grid tables are most similar to tables in Markdown, but list tables are usually much easier to use. -See the `Sphinx documentation `_ for all table syntax alternatives. +reST supports different markup for tables. Grid tables are most similar to tables in +Markdown, but list tables are usually much easier to use. See the `Sphinx documentation +`_ for all table syntax alternatives. Both markups result in the following output: .. list-table:: - :header-rows: 1 + :header-rows: 1 + + * - Header 1 + - Header 2 + * - Cell 1 - * - Header 1 - - Header 2 - * - Cell 1 + Second paragraph cell 1 + - Cell 2 + * - Cell 3 + - Cell 4 - Second paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 Grid tables ~~~~~~~~~~~ -See `grid tables`_ for reference. +See `grid tables +`__ for +reference. -.. code:: +.. code-block:: + + +----------------------+------------+ + | Header 1 | Header 2 | + +======================+============+ + | Cell 1 | Cell 2 | + | | | + | 2nd paragraph cell 1 | | + +----------------------+------------+ + | Cell 3 | Cell 4 | + +----------------------+------------+ - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | 2nd paragraph cell 1 | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ List tables ~~~~~~~~~~~ -See `list tables`_ for reference. +See `list tables +`__ for +reference. .. code:: - .. list-table:: - :header-rows: 1 + .. list-table:: + :header-rows: 1 + + * - Header 1 + - Header 2 + * - Cell 1 - * - Header 1 - - Header 2 - * - Cell 1 + 2nd paragraph cell 1 + - Cell 2 + * - Cell 3 + - Cell 4 - 2nd paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 Data tables ~~~~~~~~~~~ @@ -654,24 +704,24 @@ For example: .. code-block:: rst .. csv-table:: - :header: "Animal", "Number of legs", "Size" + :header: "Animal", "Number of legs", "Size" - "Worm", 0, "Small" - "Penguin", 2, "Medium" - "Horse", 4, "Large" - "Ant", 6, "Small" - "Octopus", 8, "Medium" + "Worm", 0, "Small" + "Penguin", 2, "Medium" + "Horse", 4, "Large" + "Ant", 6, "Small" + "Octopus", 8, "Medium" -If you have a large amount of CSV data, or the data is generated by an automated process, -you can include the data from a file. +If you have a large amount of CSV data, or the data is generated by an automated +process, you can include the data from a file. For example: .. code-block:: rst .. csv-table:: - :file: /reuse/animals.csv - :header-rows: 1 + :file: /assets/animals.csv + :header-rows: 1 Both markups result in the following output: @@ -684,31 +734,33 @@ Both markups result in the following output: "Ant", 6, "Small" "Octopus", 8, "Medium" -Customize the column widths, character encoding, and so on, as described in the -`csv-table reference `_. +Customize the column widths, character encoding, and so on, as described in the +`csv-table reference +`_. + +The Sphinx Stack can also render interactive tables. See: :ref:`interactive-tables`. -The Starter Pack can also render interactive tables. See: :ref:`interactive-tables`. Notes ----- .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Input - - Output - * - .. code:: + * - Input + - Output + * - .. code:: - .. note:: - A note. - - .. note:: - A note. - * - .. code:: + .. note:: + A note. + - .. note:: + A note. + * - .. code:: - .. warning:: - This might damage your hardware! - - .. warning:: - This might damage your hardware! + .. warning:: + This might damage your hardware! + - .. warning:: + This might damage your hardware! Adhere to the following conventions: @@ -716,92 +768,101 @@ Adhere to the following conventions: - Only use the following note types: ``note``, ``warning`` - Only use a warning if there is a clear hazard of hardware damage or data loss. + Images ------ .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Input - - Output - * - ``.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png`` - - .. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - * - .. code:: + * - Input + - Output + * - ``.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png`` + - .. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + * - .. code:: - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text + .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text - Figure caption - - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text + Figure caption + - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text - Figure caption + Figure caption Adhere to the following conventions: -- For local pictures, start the path with :file:`/` (for example, :file:`/images/image.png`). +- For local pictures, start the path with ``/`` (for example, ``/images/image.png``). - Use ``PNG`` format for screenshots and ``SVG`` format for graphics. - If producing multiple output formats, use ``*`` as the file extension to have Sphinx select the best image format for the output -- See `Five golden rules for compliant alt text`_ for information about how to word the alt text. +- See `Five golden rules for compliant alt text + `__ + for information about how to word the alt text. + Reuse ----- -A big advantage of reST in comparison to plain Markdown is that it allows to reuse content. +A big advantage of reST in comparison to plain Markdown is that it allows to reuse +content. + + +.. _reference-substitution-syntax: Substitution ~~~~~~~~~~~~ -To reuse sentences and entire paragraphs -that have little markup or special formatting, -define `substitutions`_ for them in two possible ways. +To reuse sentences and entire paragraphs that have little markup or special formatting, +define `substitutions +`__ +for them in two possible ways. -**Globally**, in a file named :file:`reuse/substitutions.txt` -that is included in a custom ``rst_epilog`` directive -(see the `Sphinx documentation `_): +**Globally**, in a file named ``reuse/substitutions.txt`` that is included in a +custom ``rst_epilog`` directive (see the `rst_epilog documentation +`_): .. code-block:: python - :caption: :spellexception:`conf.py` + :caption: :spellexception:`conf.py` - rst_epilog = """ - .. include:: reuse/substitutions.txt - """ + rst_epilog = """ + .. include:: reuse/substitutions.txt + """ .. code-block:: rest - :caption: :spellexception:`reuse/substitutions.txt` + :caption: :spellexception:`reuse/substitutions.txt` - .. |version_number| replace:: 0.1.0 + .. |version_number| replace:: 0.1.0 - .. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. + .. |rest_text| replace:: *Multi-line* text + that uses basic **markup**. - .. |site_link| replace:: Website link - .. _site_link: https://example.com + .. |site_link| replace:: Website link + .. _site_link: https://example.com **Locally**, putting the same directives in any reST file: .. code-block:: rest - :caption: :spellexception:`index.rst` + :caption: :spellexception:`index.rst` - .. |version_number| replace:: 0.1.0 + .. |version_number| replace:: 0.1.0 - .. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. + .. |rest_text| replace:: *Multi-line* text + that uses basic **markup**. - .. And so on + .. And so on .. note:: - Mind that substitutions can't be redefined; - for instance, accidentally including a definition twice causes an error: + Mind that substitutions can't be redefined; for instance, accidentally including a + definition twice causes an error: - .. code-block:: none + .. code-block:: none ERROR: Duplicate substitution definition name: "rest_text". @@ -809,37 +870,44 @@ that is included in a custom ``rst_epilog`` directive The definitions from the above examples are rendered as follows: .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Input - - Output + * - Input + - Output - * - ``|version_number|`` - - |version_number| + * - ``|version_number|`` + - |version_number| - * - ``|rest_text|`` - - |rest_text| + * - ``|rest_text|`` + - |rest_text| - * - ``|site_link|_`` - - |site_link|_ + * - ``|site_link|_`` + - |site_link|_ .. tip:: - Use substitution names that hint at the included content - (for example, ``note_not_supported`` instead of ``note_substitution``). + Use substitution names that hint at the included content (for example, + ``note_not_supported`` instead of ``note_substitution``). File inclusion ~~~~~~~~~~~~~~ -To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations. +To reuse longer sections or text with more advanced markup, you can put the content in a +separate file and include the file or parts of the file in several locations. -To select parts of the text in a file, use ``:start-after:`` and ``:end-before:`` if possible. You can combine those with ``:start-line:`` and ``:end-line:`` if required (if the same text occurs more than once). Using only ``:start-line:`` and ``:end-line:`` is error-prone though. +To select parts of the text in a file, use ``:start-after:`` and ``:end-before:`` if +possible. You can combine those with ``:start-line:`` and ``:end-line:`` if required (if +the same text occurs more than once). Using only ``:start-line:`` and ``:end-line:`` is +error-prone though. -You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file. +You cannot put any targets into the content that is being reused (because references to +this target would be ambiguous then). You can, however, put a target right before +including the file. -By combining file inclusion and substitutions defined directly in a file, you can even replace parts of the included text. +By combining file inclusion and substitutions defined directly in a file, you can even +replace parts of the included text. .. list-table:: :header-rows: 1 @@ -857,94 +925,74 @@ By combining file inclusion and substitutions defined directly in a file, you ca Adhere to the following conventions: -- Files that only contain text that is reused somewhere else should be placed in the :file:`reuse` folder and end with the extension ``.txt`` to distinguish them from normal content files. -- To make sure inclusions don't break, consider adding comments (``.. some comment``) to the source file as markers for starting and ending. +- Files that only contain text that is reused somewhere else should be placed in the + ``reuse`` directory and end with the extension ``.txt`` to distinguish them from + normal content files. +- To make sure inclusions don't break, consider adding comments (``.. some comment``) to + the source file as markers for starting and ending. + Tabs ---- -The recommended way of creating tabs is to use the tabs that the `Sphinx design`_ extension provides. +The recommended way of creating tabs is to use the tabs that the `Sphinx design +`__ extension provides. .. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. tab-set:: - - .. tab-item:: Tab 1 - :sync: key1 - - Content Tab 1 - - .. tab-item:: Tab 2 - :sync: key2 - - Content Tab 2 - - .. tab-set:: - - .. tab-item:: Tab 1 - :sync: key1 - - Content Tab 1 - - .. tab-item:: Tab 2 - :sync: key2 - - Content Tab 2 - -Alternatively, you can use the `Sphinx tabs`_ extension, which is also enabled by default. This was previously recommended due to limitations in Sphinx Design that are now fixed. + :header-rows: 1 -.. list-table:: - :header-rows: 1 + * - Input + - Output + * - .. code:: - * - Input - - Output - * - .. code:: + .. tab-set:: - .. tabs:: + .. tab-item:: Tab 1 + :sync: key1 - .. group-tab:: Tab 1 + Content Tab 1 - Content Tab 1 + .. tab-item:: Tab 2 + :sync: key2 - .. group-tab:: Tab 2 + Content Tab 2 + - .. tab-set:: - Content Tab 2 - - .. tabs:: + .. tab-item:: Tab 1 + :sync: key1 - .. group-tab:: Tab 1 + Content Tab 1 - Content Tab 1 + .. tab-item:: Tab 2 + :sync: key2 - .. group-tab:: Tab 2 + Content Tab 2 - Content Tab 2 Glossary -------- -You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file. +You can define glossary terms in any file. Ideally, all terms should be collected in one +glossary file though, and they can then be referenced from any file. .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Input - - Output - * - .. code:: + * - Input + - Output + * - .. code:: - .. glossary:: + .. glossary:: - an example term - Definition of an example term. - - .. glossary:: + an example term + Definition of an example term. + - .. glossary:: + + an example term + Definition of an example term. + * - ``:term:`an example term``` + - :term:`an example term` - an example term - Definition of an example term. - * - ``:term:`an example term``` - - :term:`an example term` .. _section_more_useful_markup: @@ -952,41 +1000,36 @@ More useful markup ------------------ .. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - * - .. code:: - - .. versionadded:: X.Y - - .. versionadded:: X.Y - - Can be used to distinguish between different versions. - * - .. code:: - - | Line 1 - | Line 2 - | Line 3 - - | Line 1 - | Line 2 - | Line 3 - - Line breaks that are not paragraphs. Use this sparingly. - * - .. code:: + :header-rows: 1 - ---- - - A horizontal line - - Can be used to visually divide sections on a page. - * - ``.. This is a comment`` - - .. This is a comment - - Not visible in the output. - * - ``:abbr:`API (Application Programming Interface)``` - - :abbr:`API (Application Programming Interface)` - - Hover to display the full term. - * - ``:spellexception:`PurposelyWrong``` - - :spellexception:`PurposelyWrong` - - Explicitly exempt a term from the spelling check. - -.. LINKS - -.. _substitutions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions -.. _rst_epilog: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog + * - Input + - Output + - Description + * - .. code:: + + .. versionadded:: X.Y + - .. versionadded:: X.Y + - Can be used to distinguish between different versions. + * - .. code:: + + | Line 1 + | Line 2 + | Line 3 + - | Line 1 + | Line 2 + | Line 3 + - Line breaks that are not paragraphs. Use this sparingly. + * - .. code:: + + ---- + - A horizontal line + - Can be used to visually divide sections on a page. + * - ``.. This is a comment`` + - .. This is a comment + - Not visible in the output. + * - ``:abbr:`API (Application Programming Interface)``` + - :abbr:`API (Application Programming Interface)` + - Hover to display the full term. + * - ``:spellexception:`PurposelyWrong``` + - :spellexception:`PurposelyWrong` + - Explicitly exempt a term from the spelling check. diff --git a/docs/release-notes/1.5.rst b/docs/release-notes/1.5.rst index 45bf075..c3b8c81 100644 --- a/docs/release-notes/1.5.rst +++ b/docs/release-notes/1.5.rst @@ -11,13 +11,13 @@ Canonical's Sphinx Starter Pack 1.5 These release notes cover new features and changes in Canonical's Sphinx Starter Pack 1.5. The `full commit log -`__ is available +`__ is available on GitHub. Bring these changes into your docs: -- :ref:`Update starter pack 1.3.0 and higher ` -- :ref:`Update starter pack 1.2.0 and lower ` +- :ref:`Update starter pack 1.3.0 and higher ` +- :ref:`Update starter pack 1.2.0 and lower ` What's new in 1.5 @@ -48,8 +48,7 @@ to the latest minor version. New upgrade guide ~~~~~~~~~~~~~~~~~ -For docs based on starter pack 1.3 or higher, we published -:ref:`update-new-starter-pack`. +For docs based on starter pack 1.3 or higher, we published :ref:`update-new-sphinx-stack`. Contribution guide @@ -57,7 +56,7 @@ Contribution guide We've added a contribution guide for the project in ``CONTRIBUTING.md``. It's available in upgraded repositories and `on GitHub -`__. +`__. This guide is for developers of the starter pack. It's not meant for your project. After updating, remove it from your project. diff --git a/docs/release-notes/1.6.rst b/docs/release-notes/1.6.rst index 52feaad..216cf40 100644 --- a/docs/release-notes/1.6.rst +++ b/docs/release-notes/1.6.rst @@ -11,13 +11,13 @@ Canonical's Sphinx Starter Pack 1.6 These release notes cover new features and changes in Canonical's Sphinx Starter Pack 1.6. The `full commit log -`__ is available +`__ is available on GitHub. Bring these changes into your docs: -- :ref:`Update starter pack 1.3.0 and higher ` -- :ref:`Update starter pack 1.2.0 and lower ` +- :ref:`Update Starter Pack 1.3.0 and higher ` +- :ref:`Update Starter Pack 1.2.0 and lower ` What's new in 1.6 @@ -55,7 +55,7 @@ For example, if you were previously redirecting ``/how-to/set-up/project/`` to :caption: redirects.txt :class: no-copybutton - "/how-to/set-up/project/" "/how-to/set-up-project/" + "how-to/set-up/project/" "how-to/set-up-project/" Remote cookie banner files diff --git a/docs/release-notes/2.0.rst b/docs/release-notes/2.0.rst new file mode 100644 index 0000000..6ddd584 --- /dev/null +++ b/docs/release-notes/2.0.rst @@ -0,0 +1,274 @@ +.. meta:: + :description: The new features, changes, and fixes in Sphinx Stack 2.0. + + +.. _release-2.0: + +Canonical's Sphinx Starter Pack 2.0 +==================================== + +30 April 2026 + +These release notes cover new features and changes in the project formerly known as +Canonical's Sphinx Starter Pack. For a more granular list of changes, check out the full +commit log. + +Bring these changes into your docs: + +- :ref:`Update Starter Pack 1.3.0 and higher ` +- :ref:`Update Starter Pack 1.2.0 and lower ` + + +What's new +---------- + +Rename to Sphinx Stack +~~~~~~~~~~~~~~~~~~~~~~ + +This project was named when the documentation team at Canonical started assembling a +standard documentation toolkit. The word starter felt appropriate, as products needed +their documentation bootstrapped, and we had yet to release a standard. More than two +years later, this is no longer the case. This project has been deployed in hundreds of +Canonical products. It represents a complete standard for Canonical documentation sets, +not just those starting out. So, we decided that it's time for a new name. + +With the release of version 2.0, we're renaming the project **Sphinx Stack**. The +repository is now located at https://github.com/canonical/sphinx-stack. + + +Separate documentation repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To simplify the process of setting up and maintaining the Sphinx Stack, we separated its +documentation into a new `Sphinx Stack documentation repository +`__. + +Now, when you create a new project with the Sphinx Stack, you no longer need to remove +its documentation. New projects are also no longer initialized with any configuration +specific to the Sphinx Stack docs. Now, there's less ambiguity as to whether you need to +incorporate new values into your configuration file. + + +sphinx-llm support +~~~~~~~~~~~~~~~~~~ + +This version introduces default support for the `sphinx-llm +`__ extension. It surfaces documents in accordance +with the emerging `llms.txt standard `__. + +You can think of the ``llms.txt`` file as an extra sitemap for LLMs and systems using +the Model Context Protocol. In your documentation builds, you'll now see an ``llms.txt`` +file, an ``llms-full.txt`` file, and Markdown copies of your pages. The content of these +files is copied straight from your existing docs -- it doesn't transform or summarize +the text. + + +Dependency constraints +~~~~~~~~~~~~~~~~~~~~~~ + +In the past, we've had upstream packages break documentation builds without warning. To +reduce this, we constrained the project's dependencies to their current major version. + +Before every future major release, we'll test the newest versions and adjust the +constraints appropriately. + + +Copyright statement +~~~~~~~~~~~~~~~~~~~ + +We aligned the copyright statement in the footer with legal standards. To incorporate +this change in your documentation, add the license information to ``html_context`` in +your ``conf.py`` file: + +.. code-block:: python + :caption: docs/conf\.py + + html_context = { + "license": { + "name": "CC-BY-SA-3.0", + "url": "https://github.com/canonical/sphinx-stack/blob/main/LICENSE", + }, + } + +For ``license.name``, use the standard shorthand identifier from `SPDX +`__. + +For ``license.url``, link to the LICENSE statement, typically found on the product's +home page or in its GitHub repository. + + +Ulwazi testing +~~~~~~~~~~~~~~ + +We invite you to :ref:`test Ulwazi `, our new documentation +theme in early access. + +It represents a leap forward in the user experience, and we'd like your feedback. If you +run into any bugs or issues, please `report them on GitHub +`__. + + +Breaking changes +---------------- + + +Renamed the ``.sphinx/`` directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``.sphinx/`` directory, which contains config files and utility scripts, has been +renamed to ``_dev`` to better reflect its purpose. + +Once you've updated, remember to remove the ``.sphinx`` directory from your project. If +your project has custom code that references this directory, you'll also need to update +these references. + + +Removed the ``reuse/`` directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To reduce complexity and improve source readability, we've removed the ``reuse/`` +directory. + +By default, this directory contained project-wide link URLs and substitutions. Links +should now be included with the inline syntax or, if used more than three times in a +file, included at the end of the file. Substitutions will need to use reST or MyST +syntax and should be placed at the top of the file. The syntax for these changes is +described in :ref:`External links ` and +:ref:`Substitution `. + + +Deprecated features +------------------- + +The following features are deprecated. We plan to remove them in the 3.0 release. + + +``none`` role +~~~~~~~~~~~~~ + +The ``none`` role is deprecated in 2.0. + +To prepare for this role's removal, replace any uses of it with comments. + +.. code-block:: diff + + - :none:`This text isn't rendered.` + + .. This text isn't rendered. + + +sphinx-tabs extension +~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-tabs extension is deprecated in 2.0. + +If your documentation contains ``tabs`` and ``tab`` directives, replace them with the +``tab-set`` and ``tab-item`` directives from the sphinx-design extension: + +.. code-block:: diff + + - .. tabs:: + - + - .. tab:: Item 1 + - + - This is the first item. + - + - .. tab:: Item 2 + - + - This is the second item. + + .. tab-set:: + + + + .. tab-item:: Item 1 + + + + This is the first item. + + + + .. tab-item:: Item 2 + + + + This is the second item. + + +sphinx-contributor-listing extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-contributor-listing extension is deprecated in 2.0. To simplify the header +and footer design, we're ending support for per-page contributor lists in the next major +release. + + +sphinx-filtered-toctree extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-filtered-toctree extension is deprecated in 2.0. This extension was part of a +legacy feature and is no longer needed. + +If your ``conf.py`` file assigns a value to ``toc_filter_exclude``, remove the line: + +.. code-block:: diff + :caption: docs/conf\.py + + - toc_filter_exclude = ["foo", "bar"] + +Then, replace any ``filtered-toctree`` directives with the ``toctree`` directive. If you +find a page prefixed with one of the strings previously listed with toc_filter_exclude, +evaluate its usefulness. If it should be rendered, remove the prefix. If not, delete the +entry and its respective file. + +.. code-block:: diff + + - .. filtered-toctree:: + - + - page-a + - :foo:page-b + + .. toctree:: + + + + page-a + + +sphinx-last-updated-by extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-last-updated-by-git extension is deprecated in 2.0. Its inclusion in the +docs/requirements.txt file is redundant, as it's already set up by the sphinx-sitemap +extension. + +Ensure that you have the sphinx-sitemap extension installed and configured. For +guidance, refer to :ref:`sitemaps`. + + +sphinx-ubuntu-images extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-ubuntu-images extension is deprecated in 2.0. This extension isn't commonly +used and won't be included by default in the next major release. + +If your documentation uses the ``ubuntu-images`` directive, be sure to add it back to +your ``requirements.txt`` and ``conf.py`` files after you update. + + +sphinx-reredirects extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sphinx-reredirects extension was deprecated in 1.6. Redirects, both internal and +external, should now be handled with the sphinx-rerediraffe extension. + +:ref:`how-to-redirect-pages` contains guidance on redirecting pages with the +sphinx-rerediraffe extension. + + +Contributors +------------ + +We'd like to express a big thank you to everyone who contributed to this release: + +:literalref:`a-velasco `, +:literalref:`asanvaq `, +:literalref:`AshleyCliff `, +:literalref:`izmalk `, +:literalref:`jahn-junior `, +:literalref:`keirthana `, +:literalref:`medubelko `, +:literalref:`mhsun-se `, +:literalref:`nhennigan `, +:literalref:`odadacharles `, +:literalref:`Saviq `, +:literalref:`srbouffard `, and +:literalref:`yhontyk `, diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 71c070a..aef7dfa 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -3,20 +3,21 @@ Release notes ============= -This page lists the notes for past releases of Canonical's Sphinx Starter Pack, which +This page lists the notes for past releases of the Sphinx Stack, which summarize new features, bug fixes and breaking changes in each version. It also contains -the release and support policies for the starter pack. +the release and support policies for the Sphinx Stack. Latest release -------------- -- :ref:`release-1.6` +- :ref:`release-2.0` Past releases ------------- +- :ref:`release-1.6` - :ref:`release-1.5` - :ref:`release-1.4` @@ -24,7 +25,7 @@ Past releases Release versioning ------------------ -Starter pack version naming follows the Semantic Versioning 2.0.0 scheme with +Sphinx Stack version naming follows the Semantic Versioning 2.0.0 scheme with modifications. It has numbers for major and minor version, but *not* patch versions. .. list-table:: @@ -44,6 +45,7 @@ modifications. It has numbers for major and minor version, but *not* patch versi .. toctree:: :hidden: + 2.0 <2.0> 1.6 <1.6> 1.5 <1.5> 1.4 <1.4> diff --git a/docs/requirements.txt b/docs/requirements.txt index 6016a35..69c0782 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,30 +4,31 @@ canonical-sphinx~=0.6 # Extensions previously auto-loaded by canonical-sphinx myst-parser~=4.0 # v5.0.0 causes version conflicts sphinx-autobuild -sphinx-design -sphinx-notfound-page -sphinx-reredirects -sphinx-tabs -sphinxcontrib-jquery -sphinxext-opengraph -sphinx-rerediraffe +sphinx-design==0.6.1 +sphinx-notfound-page~=1.1 +sphinx-reredirects==0.1.6 +sphinx-tabs~=3.5 +sphinxcontrib-jquery~=4.1 +sphinxext-opengraph~=0.13 +sphinx-rerediraffe>=0.0.3, <1.0.0 # Extra extensions, previously bundled as canonical-sphinx-extensions -sphinx-config-options>=0.1.0 -sphinx-contributor-listing>=0.1.0 -sphinx-filtered-toctree>=0.1.0 -sphinx-related-links>=0.1.2 -sphinx-roles>=0.1.0 -sphinx-terminal>=1.0.2 -sphinx-ubuntu-images>=0.1.0 -sphinx-youtube-links>=0.1.0 +sphinx-config-options~=0.1 +sphinx-contributor-listing~=0.1 +sphinx-filtered-toctree~=0.1 +sphinx-related-links~=0.1 +sphinx-roles~=0.1 +sphinx-terminal~=1.0 +sphinx-ubuntu-images~=0.1 +sphinx-youtube-links~=0.1 # Other dependencies -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap +packaging~=26.1 +sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1 +sphinx-last-updated-by-git~=0.3 +sphinx-sitemap~=2.9 +sphinx-llm~=0.4 # Vale dependencies rst2html -vale +vale~=3.13 \ No newline at end of file diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt deleted file mode 100644 index af3c3b5..0000000 --- a/docs/reuse/links.txt +++ /dev/null @@ -1,46 +0,0 @@ -.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en -.. _Canonical Reference Library: https://library.canonical.com/ -.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx -.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log -.. _csv-table reference: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table -.. _csv-table reference (MyST): https://mystmd.org/guide/directives#directive-csv-table -.. _Diátaxis: https://diataxis.fr/ -.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ -.. _Example product documentation repository: https://github.com/canonical/example-product-documentation -.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html -.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text -.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ -.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables -.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ -.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html -.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html -.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs -.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance -.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table -.. _manual import: https://readthedocs.com/dashboard/import/manual/ -.. _Markdown: https://commonmark.org/ -.. _MyST: https://myst-parser.readthedocs.io/ -.. _Open Graph: https://ogp.me/ -.. _Pa11y: https://pa11y.org/ -.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration -.. _Pygments documentation: https://pygments.org/languages/ -.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _`Sphinx`: https://www.sphinx-doc.org/ -.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html -.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/ -.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ -.. _Sphinx documentation starter pack: -.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack -.. _Sphinx documentation starter pack documentation: https://canonical-starter-pack.readthedocs-hosted.com/ -.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html -.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. _tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives -.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree -.. _Vale: https://vale.sh/ -.. _Vale rules: https://github.com/canonical/documentation-style-guide -.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ - - -.. SHORTCUTS -.. |RST| replace:: :abbr:`reST (reStructuredText)` diff --git a/docs/reuse/substitutions.txt b/docs/reuse/substitutions.txt deleted file mode 100644 index 307b5f2..0000000 --- a/docs/reuse/substitutions.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. |version_number| replace:: 0.1.0 - -.. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - -.. |site_link| replace:: Website link -.. _site_link: https://example.com \ No newline at end of file diff --git a/docs/reuse/substitutions.yaml b/docs/reuse/substitutions.yaml deleted file mode 100644 index 0c2958d..0000000 --- a/docs/reuse/substitutions.yaml +++ /dev/null @@ -1,4 +0,0 @@ -# Key/value substitutions to use within the Sphinx doc. -{version_number: "0.1.0", - formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} \ No newline at end of file diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst index 159e7cf..9e01411 100644 --- a/docs/set-up-a-new-project.rst +++ b/docs/set-up-a-new-project.rst @@ -1,139 +1,164 @@ .. _set-up-a-new-project: -=================================== + Set up a new project -=================================== +==================== -This page contains a short guide on how to set up and use the starter pack. +This page contains a short guide on how to set up and use the Sphinx Stack. .. _initial-setup: -Copy the starter pack -===================== +Copy the Sphinx Stack +--------------------- -If you're starting a new project, `copy the starter pack as a template repository `__. +If you're starting a new project, `copy the Sphinx Stack as a template repository +`__. -If you're creating documentation for a Canonical project, set the owner to **canonical**. +If you're creating documentation for a Canonical project, set the owner to +**canonical**. -If you're adding documentation to an existing software project, copy the following files from the starter pack repository into your project: +If you're adding documentation to an existing software project, copy the following files +from the Sphinx Stack repository into your project: -* the entire :file:`docs` directory -* :file:`.readthedocs.yaml` (configuration for the building on Read the Docs) -* the entire :file:`.github/workflows` directory +* the entire ``docs`` directory +* ``.readthedocs.yaml`` (configuration for the building on Read the Docs) +* the entire ``.github/workflows`` directory .. _remove-unneeded-files: Remove the unneeded files -========================= +------------------------- -Next, review the starter pack files and remove those that could interfere with your project. +Next, review the Sphinx Stack files and remove those that could interfere with your +project. Remove the files that can't be reused: -- :file:`CONTRIBUTING.md` -- :file:`.github/CODEOWNERS` -- :file:`.github/workflows/test-starter-pack.yml` +- ``CONTRIBUTING.md`` +- ``.github/CODEOWNERS`` +- ``.github/workflows/test-sphinx-stack.yml`` -Review and remove the GitHub workflows in ``.github/workflows/`` that your project might not need: +Review and remove the GitHub workflows in ``.github/workflows/`` that your project might +not need: -- :file:`cla-check.yml` verifies whether contributors have signed the `Canonical License Agreement `_. All Canonical projects require this check, so if you're adding docs to an existing Canonical project that already has it, remove this workflow. -- :file:`sphinx-python-dependency-build-checks.yml` verifies Python dependencies for the documentation system. If your project has its own dependency checks, remove this workflow. -- :file:`markdown-style-checks.yml` runs the built-in Markdown linter. If your project already validates its Markdown files, remove this workflow. +- ``cla-check.yml`` verifies whether contributors have signed the `Canonical License + Agreement `_. All Canonical projects require + this check, so if you're adding docs to an existing Canonical project that already has + it, remove this workflow. +- ``sphinx-python-dependency-build-checks.yml`` verifies Python dependencies for the + documentation system. If your project has its own dependency checks, remove this + workflow. +- ``markdown-style-checks.yml`` runs the built-in Markdown linter. If your project + already validates its Markdown files, remove this workflow. Build and run the local server -============================== +------------------------------ + +Building the documentation requires ``make``, ``python3``, ``python3-venv``, +``python3-pip``. -Building the documentation requires ``make``, ``python3``, ``python3-venv``, ``python3-pip``. +In the ``docs`` directory, run: -In :file:`docs`, run:: +.. code-block:: bash make run -This creates and activates a virtual environment in :file:`docs/.venv`, builds the documentation and serves it at :literalref:`http://127.0.0.1:8000/`. +This creates and activates a virtual environment in ``docs/.venv``, builds the project, +and serves it at :literalref:`http://127.0.0.1:8000/`. -The server watches the source files, including :file:`docs/conf.py`, and rebuilds automatically on changes. +The server watches the source files, including the ``docs/conf.py`` file, and rebuilds +automatically on changes. Edit content -============== +------------ -Now that you've verified you can build and run the sample starter pack documentation, you can replace it with your own content. +The home page is ``docs/index.rst``. Other pages are under one of the sub-directories +under ``docs/``. -The landing page is :file:`docs/index.rst`. Other pages are under one of the sub-directories under :file:`docs/`. - -The navigation menu structure is set by ``.. toctree::`` directives. These directives define the hierarchy of included content throughout the documentation. -The :file:`index.rst` page's ``toctree`` block contains the top level navigation, which by default is the `Diátaxis`_ documentation structure. +The navigation menu structure is set by ``.. toctree::`` directives. These directives +define the hierarchy of included content throughout the documentation. The +``index.rst`` page's ``toctree`` block contains the top level navigation, which by +default is the `Diátaxis `__ documentation structure. To add a new page to the documentation: -1. Create a new file in the `docs/` folder. For example, to create a new **Reference** page, create a document under `docs/reference/` directory called :file:`settings.rst`, insert the following |RST|-formatted heading ``Settings`` at the beginning, and then save the file: +1. Create a new file in the ``docs/`` directory. For example, to create a new + **Reference** page, create a document under the ``docs/reference/`` directory called + ``settings.rst``, insert the following heading, and save the file: .. code-block:: rest :caption: reStructuredText title example - Settings - ======== + Settings + ======== - If you prefer to use Markdown (MyST) syntax instead of |RST|, you can create a Markdown file. For example, :file:`settings.md` file with the following Markdown-formatted heading at the beginning: + If you prefer to use Markdown (MyST) syntax instead of |RST|, you can create a + Markdown file. To create the equivalent ``settings.md`` file, add the following + Markdown-formatted heading at the beginning: .. code-block:: markdown :caption: Markdown title example - # Settings - -2. Add the new page to the Navigation Menu: open the :file:`docs/reference/index.rst` file or another file where you want to nest the new page; at the bottom of the file, locate the ``toctree`` directive and add a properly indented line containing the relative path (without a file extension) to the new file created in the first step. For example, ``settings``. + # Settings - The ``toctree`` block will now look like this: +2. Add the new page to the Navigation Menu: open the ``docs/reference/index.rst`` + file or another file where you want to nest the new page; at the bottom of the file, + add the following ``toctree`` directive: - .. code-block:: rest + .. code-block:: - .. toctree:: - :hidden: - :maxdepth: 2 + .. toctree:: + :hidden: + :maxdepth: 2 - Documentation checks - style-guide - style-guide-myst - settings + settings The documentation will now show the new page added to the navigation when rebuilt. -By default, the page's title (the first heading in the file) is used for the Navigation Menu entry. You can overwrite a name of a Menu element by specifying it explicitly in the ``toctree`` block, for example: ``Reference ``. +By default, the page's title (the first heading in the file) is shown in the global +navigation. You can overwrite a name of a menu element by specifying it explicitly in +the ``toctree`` block (e.g., ``Reference ``). -Configure settings -================== +Configure Sphinx +---------------- -Work through the settings in :file:`docs/conf.py`. Most parameters can be left with the default values as they can be changed later. :ref:`configure-your-project` contains further guidance. +Work through the settings in the build configuration file, ``docs/conf.py``. Most +parameters can be left with the default values as they can be changed later. +:ref:`configure-your-project` contains further guidance. -Pre-commit hooks (optional) -=========================== +Configure pre-commit (optional) +------------------------------- -Use `pre-commit `_ hooks with the starter pack -to automate checks like spelling and inclusive language. +Use `pre-commit `_ hooks with the Sphinx Stack to automate +checks like spelling and inclusive language. -The starter pack includes a ready-to-use :file:`.pre-commit-config.yaml` file -under :file:`docs/.sphinx/`: +The Sphinx Stack includes a ready-to-use ``.pre-commit-config.yaml`` file under +``docs/_dev/``: -.. literalinclude:: /.sphinx/.pre-commit-config.yaml +.. literalinclude:: /_dev/.pre-commit-config.yaml :language: yaml -For a new project, copy this file to your project's root directory; -for an existing project using ``pre-commit``, -add these hooks to your configuration. +For a new project, copy this file to your project's root directory. For an existing +project using pre-commit, add these hooks to your configuration. + +To apply the configuration, install the Sphinx Stack hooks, for instance: + +.. code-block:: bash -To apply the configuration, install the starter pack hooks, for instance:: + pre-commit install --config docs/_dev/.pre-commit-config.yaml - pre-commit install --config docs/.sphinx/.pre-commit-config.yaml +After that, you should see the checks running with every commit: -After that, you should see the checks running with every commit:: +.. terminal:: - git commit -m 'add spelling errors' + git commit -m 'add spelling errors' - Run make spelling.......................................................Failed - Run make linkcheck......................................................Passed - Run make woke...........................................................Passed + Run make spelling.......................................................Failed + Run make linkcheck......................................................Passed + Run make woke...........................................................Passed