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 e50e4d8f..bfbf5036 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 index 1c6831f2..cf12b974 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,11 @@ * Remove `reuse/` directory * Rename `.sphinx/` directory to `_dev/` * Add default configuration for copyright and license statements +* Remove docs and project-specific configuration ### Changed -* `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) +* `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590), [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) * `docs/Makefile` [#575](https://github.com/canonical/sphinx-docs-starter-pack/pull/575), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590) * `docs/requirements.txt` [#590]([#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590)) * `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) @@ -19,6 +20,8 @@ * `docs/_templates/footer.html` [#594](https://github.com/canonical/sphinx-docs-starter-pack/pull/594) * `docs/requirements.txt` [#596](https://github.com/canonical/sphinx-docs-starter-pack/pull/596) * `docs/redirects.txt` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) +* `docs/.sphinx/update_sp.py` [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595) +* `.github/workflows/test-sphinx-stack.yml` [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595) ## 1.6 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a17d8e28..11de6792 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,23 @@ -# Contributing to the Starter Pack +# Contributing to Sphinx Stack development -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 development. If you're interested in +> contributing to the Sphinx Stack documentation, refer to the [documentation +> repository's +> guide](https://github.com/canonical/sphinx-stack-docs/blob/main/CONTRIBUTING.md). ## Review the project expectations @@ -17,62 +25,78 @@ 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 [GPL-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 you find a bug or feature gap in the Sphinx Stack, look for it in the [project's +GitHub issues](https://github.com/canonical/sphinx-stack/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). +If the bug or feature doesn't have an issue, [open +one](https://github.com/canonical/sphinx-stack/issues/new/choose). -## What belongs in the Starter Pack +## What belongs in the Sphinx Stack -The Starter Pack is designed to be a minimal, flexible foundation for diverse documentation projects. +The Sphinx Stack is designed to be a minimal, flexible foundation for diverse +documentation projects. -**Belongs in the Starter Pack:** +**Belongs in the Sphinx Stack:** - Bug fixes for core functionality - Improvements to default configuration that benefit all users -- Documentation about existing features - Dependency updates for security or compatibility -**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 +**May not belong in the Sphinx Stack:** +- Optional tooling or features (these should be opt-in and implemented by projects using + the Sphinx Stack) +- 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) +- 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. +When in doubt, open an issue first to discuss whether the change aligns with the +project's goals. ## 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/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 +cd sphinx-stack +git remote add upstream git@github.com:canonical/sphinx-stack 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 +cd sphinx-stack +git remote add upstream https://github.com/canonical/sphinx-stack git fetch upstream ``` @@ -88,15 +112,21 @@ 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/issues) for +existing reports. If none exist, [open +one](https://github.com/canonical/sphinx-stack/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 the plan, tests, and +documentation. For new documentation pages, propose a [Diátaxis](https://diataxis.fr) +category. ### Create a development branch @@ -107,15 +137,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-string-sanitizer`), +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 @@ -134,7 +165,8 @@ 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 +181,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 @@ -203,15 +248,18 @@ 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. +This documentation is sourced from +[canonical/sphinx-stack-docs](https://github.com/canonical/sphinx-stack-docs) and 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). +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. +Ensure that feature changes and fixes are documented in the relevant release notes. ### Push the branch and open a PR @@ -219,7 +267,8 @@ For non-documentation changes, ensure that feature changes and fixes are documen 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 @@ -231,13 +280,13 @@ Your PR should include the following details: - 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 +305,29 @@ 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. +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`. +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 - 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. +- 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. ### Optional checks (allowed to fail) @@ -282,27 +340,21 @@ 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 31081ad4..f288702d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,13 +1,3 @@ -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 @@ -682,13 +672,3 @@ 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 diff --git a/README.md b/README.md index 526c7d55..831e27c7 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,63 @@ -# Canonical's Sphinx Starter Pack +# Sphinx Stack -*A pre-configured repository to build and publish documentation with Sphinx.* +[![Sphinx Stack test](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml/badge.svg)](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml) -## Description +A standard set of tools for building and publishing Sphinx documentation. -The Documentation Starter Pack includes: +The Sphinx Stack contains a set of CLI commands and a default set of extensions, +configuration options, and tests. -* 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 +## Basic usage -See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/ +To try out the Sphinx Stack, clone it locally and navigate to the `/docs` directory: -## Structure +```shell +git clone git@github.com:canonical/sphinx-stack.git +cd docs +``` -This section outlines the structure of this repository, and some key files. +Then, run the command -### `docs/` +```shell +make run +``` -This directory contains the documentation for the Starter Pack itself. +This will create a Python virtual environment, install necessary dependencies, build the +documentation, and serve it to http://127.0.0.1:8000. -To view it in your browser, navigate to this directory and type `make run`. +To learn more about how to install and configure the Sphinx Stack for your own project, +see the [Set up a new +project](https://canonical-sphinx-stack.readthedocs-hosted.com/stable/tutorial/set-up/) +guide in the official documentation. -### `.github/workflows/` +## Requirements and limitations -This directory contains files used for documentation build checks via GitHub's CI. +The Sphinx Stack is designed for projects hosted on GitHub. This is necessary to run the +automatic checks in .github/workflows, and to publish your documentation on Read the +Docs. -The file `test-starter-pack.yml` tests the functionality of the Starter Pack project. +If you have a project that is hosted on a different versioning platform, like Launchpad, +[reach out to us](#reach-out). -## Contributing +## Community and support -We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request. +The Sphinx Stack is an open-source project that warmly welcomes community involvement. -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). +If you’re new to the community, make sure to read through the [Ubuntu Code of +Conduct](https://ubuntu.com/community/code-of-conduct) first. - +### Reach out -[Sphinx]: https://www.sphinx-doc.org/ -[Contributor Licence Agreement (CLA)]: https://ubuntu.com/legal/contributors +* Report an issue or make a suggestion via + [GitHub](https://github.com/canonical/sphinx-stack/issues) +* Come chat with the Canonical Documentation team in our [public Matrix + channel](https://matrix.to/#/#documentation:ubuntu.com) + +### Contribute + +The Sphinx Stack provides a shared foundation for Sphinx documentation projects, and +contributions help improve the documentation of all its users. + +* See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on contributing to + development or documentation. +* Check [open issues](https://github.com/canonical/sphinx-stack/issues) diff --git a/docs/_dev/update_sp.py b/docs/_dev/update_sp.py index b4da5858..13129216 100755 --- a/docs/_dev/update_sp.py +++ b/docs/_dev/update_sp.py @@ -1,28 +1,29 @@ #! /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 _dev/update_sp.py +# e.g. user@device:~/git/Canonical/sphinx-stack/docs$ DEBUGGING=1 python .sphinx/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_DEV_DIR = f"{GITHUB_API_BASE}/contents/docs/_dev" GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main" @@ -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,7 +62,7 @@ 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 '_dev' dir files to '_dev/update' files_updated, new_files = update_static_files() @@ -130,7 +131,7 @@ def main(): except FileNotFoundError: print("requirements.txt not found") print( - "The updated starter pack has moved requirements.txt out of the '_dev' dir" + "The updated Sphinx Stack has moved requirements.txt out of the '_dev' dir" ) print("requirements.txt not checked, please update your requirements manually") @@ -142,7 +143,7 @@ def update_static_files(): for item in query_api(GITHUB_API_DEV_DIR).json(): logging.debug(f"Checking {item['name']}") - # Checks existing files in '_dev' 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]): @@ -162,9 +163,7 @@ def update_static_files(): # 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( - f"{GITHUB_API_DEV_DIR}/{item['name']}" - ).json(): + for nested_item in query_api(f"{GITHUB_API_DEV_DIR}/{item['name']}").json(): logging.debug(f"Checking {nested_item['name']}") if nested_item["name"] in files: index = files.index(nested_item["name"]) @@ -189,7 +188,7 @@ def update_static_files(): SPHINX_UPDATE_DIR, item["name"], nested_item["name"] ), ) - # Downloads NEW files in '_dev' 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']}") diff --git a/docs/_dev/version b/docs/_dev/version index 810ee4e9..cd5ac039 100644 --- a/docs/_dev/version +++ b/docs/_dev/version @@ -1 +1 @@ -1.6 +2.0 diff --git a/docs/conf.py b/docs/conf.py index 5a328587..aa203a43 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,8 +2,6 @@ import os import textwrap -import yaml - # Configuration for the Sphinx documentation builder. # All configuration specific to your project should be done in this file. # @@ -13,151 +11,92 @@ # 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 +# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") +project = "Project" -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. - +# TODO: To use a different name for the project in previews, update the next line. ogp_site_name = project - # Preview image URL -# -# TODO: To customise the preview image, update as needed. - +# TODO: To customise the preview image, update the next line. 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 = '_static/favicon.png' - +# TODO: To customise the favicon, uncomment and update the next line. +# 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 _templates/header.html; also, see README.rst). - "product_page": "documentation.ubuntu.com", + # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., + # 'ubuntu.com/lxd'). If there's no such website, remove the {{ product_page }} + # link from the _templates/header.html file. + "product_page": "", # 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", + "discourse": "", # Your Mattermost channel URL - # # TODO: Change to your Mattermost channel URL or leave empty. - "mattermost": "https://chat.canonical.com/canonical/channels/documentation", + "mattermost": "", # 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 - # + "matrix": "", + # Your documentation GitHub repository URL If set, links for viewing the + # documentation source files and creating GitHub issues are added at the bottom of + # each page. # 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": "", # 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", # 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", + # "sequential_nav": "", # TODO: To enable listing contributors on individual pages, set to True "display_contributors": False, # Required for feedback button "github_issues": "enabled", - # Inherit the author value + # Passes the top-level 'author' value to the theme "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'. + # Documentation license information "license": { - "name": "CC-BY-SA-3.0", - "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE", + # TODO: Specify your project's license. + # For the name, we recommend using the standard shorthand identifier from + # https://spdx.org/licenses + "name": "", + # TODO: Link directly to your project's license statement. + "url": "", }, } -html_extra_path = [] - -# Allow opt-in build of the OpenAPI "Hello" example so docs stay clean by default. -if os.getenv("OPENAPI", ""): - 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: @@ -166,14 +105,12 @@ # - https://git.launchpad.net/example # # html_theme_options = { -# 'source_edit_link': 'https://github.com/canonical/sphinx-docs-starter-pack', +# 'source_edit_link': 'https://github.com/canonical/sphinx-stack', # } -# 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. - +# Project slug +# TODO: If your documentation is hosted on https://documentation.ubuntu.com/, +# uncomment and set to the RTD slug. # slug = '' ####################### @@ -181,28 +118,23 @@ ####################### # 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}" # Include `lastmod` dates in the sitemap: - sitemap_show_lastmod = True -# Exclude generated pages from the sitemap: - +# TODO: Exclude pages that aren't user-facing from the sitemap (e.g., module pages +# generated by autodoc). +# Pages excluded from the sitemap: sitemap_excludes = [ "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 # ################################ @@ -210,7 +142,6 @@ # html_static_path = ["_static"] # templates_path = ["_templates"] - ############# # Redirects # ############# @@ -237,8 +168,8 @@ # ". llms_txt_description = textwrap.dedent( """\ - This is the documentation for the Sphinx Starter Pack, a template repository - that helps you set up, build, and publish Sphinx documentation. + This is the documentation for the Sphinx Stack, a template repository that helps you + set up, build, and publish Sphinx documentation. """ ) @@ -251,9 +182,6 @@ ########################### # 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", @@ -263,13 +191,14 @@ 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 +# How long the link checker will wait for a response for each request +# TODO: Decrease to improve run time or increase if links frequently time out. # linkcheck_timeout = 30 + +# Give linkcheck multiple tries on failure linkcheck_retries = 3 ######################## @@ -278,18 +207,14 @@ # 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 - +# - 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", @@ -315,65 +240,42 @@ ] # 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 -# If you have many entries, consider creating a reuse/substitutions.txt file -# and loading it here instead. +# Appends extra markup to the end of every document written in reST # rst_epilog = """ -# .. include:: reuse/substitutions.txt -# """ -rst_epilog = """ -.. |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. - +# TODO: Disable the button if your project is unsuitable for public feedback. # 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 @@ -385,30 +287,8 @@ :class: vale-ignore """ -# 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 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, - ) -} +# Configuration for Intersphinx projects +# +# intersphinx_mapping = { +# "snap": ("https://snapcraft.io/docs/", None), +# } diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst index 47504e5c..aa76b710 100644 --- a/docs/contribute/index.rst +++ b/docs/contribute/index.rst @@ -2,8 +2,3 @@ Contribute ========== - -.. toctree:: - :maxdepth: 1 - - Test the Ulwazi theme \ No newline at end of file diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md deleted file mode 100644 index 787cdec9..00000000 --- a/docs/contribute/test-ulwazi-theme.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -myst: - html_meta: - description: How to test the Ulwazi theme in a documentation project based on Canonical's Sphinx Starter Pack. -relatedlinks: "[Ulwazi on PyPI](https://pypi.org/project/ulwazi), [Vanilla](https://vanillaframework.org), [sphinx-basic-ng](https://github.com/pradyunsg/sphinx-basic-ng)" ---- - -(how-to-test-ulwazi-theme)= - -# Test the Ulwazi theme - -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. - -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 (`requirements.txt`), replace the Canonical Sphinx package with Ulwazi and its dependencies: - -```{code-block} diff -:caption: requirements.txt - -- 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 -``` - -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. - -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. - -### 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: - -```{code-block} python -:caption: conf\.py - -html_theme = "ulwazi" -``` - -#### Update the extensions - -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", -+"sphinx_terminal", -+"canonical_sphinx_config", -+"myst_parser", -+"sphinxcontrib.jquery", -``` - -If you need **PDF output**, add `sphinx_modern_pdf_style` to the extensions list and `sphinx-modern-pdf-style` to `requirements.txt`. - -```{caution} -Your project may require additional extensions beyond those listed here. -``` - -#### 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 - -You need to make several updates to the `html_context` dictionary. - -The code snippets in this section might not match the exact layout of `html_context` in your `conf.py`. - -Add these new variables, including the top-level variables you declared earlier: - -```{code-block} python -:caption: html_context in conf\.py - -"product_page": product_page, # was: "your-product.example.com" -"github_url": github_repo, # was: "https://github.com/your-org/your-repo" -"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: - -```{code-block} python -:caption: html_context in conf\.py - -"project": project, -"author": author, -``` - -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. - -```{code-block} python -:caption: html_context in conf\.py - -"feedback": True, -"github_issues": "enabled", -"default_source_extension": default_source_extension, -"default_edit_url": github_repo + "/edit/main/docs/index" + default_source_extension, -"default_view_url": github_repo + "/blob/main/docs/index" + default_source_extension, -``` - -Add the horizontal navigation menu configuration: - -```{code-block} python -:caption: html_context in conf\.py - -# Horizontal Nav Menu -"company": "Canonical", -# "link1_URL": "https://example.com/", -# "link1_name": "First optional link", -# "link2_URL": "https://example.com/", -# "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. - -Add main logo parameters and adjust their values for your documentation: - -```{code-block} python -:caption: html_context in conf\.py - -# Canonical Product menu -# Uncomment if you need a product menu added on the top of every page -# "add_product_menu": True, - -"logo_link_URL": "https://documentation.ubuntu.com", -"logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg", -"logo_title": "Canonical", -``` - -Add the following parameters for the footer. - -```{code-block} python -:caption: html_context in conf\.py - -# TODO: Customize the footer. -"footer": { - # Whether to add the product name as the first entry. - "product": True, - # Whether to add the license as the second entry. - "license": True, - # List your footer entries. Accepts HTML tags. - "entries": [ - 'Manage your tracker settings', - ] -} -``` - -#### Add syntax highlighting - -Add these syntax highlighting settings after the list of extensions: - -```{code-block} python -:caption: conf\.py - -highlight_language = "none" # default -pygments_style = "autumn" # see https://pygments.org/styles for more -``` - -#### Configure the sitemap - -Add the lastmod setting to the sitemap section: - -```{code-block} python -:caption: conf\.py - -sitemap_show_lastmod = True -``` - -#### Configure PDF output - -If you need to render your docs to PDF, add the following at the end of the configuration: - -```{code-block} python -:caption: conf\.py - -set_modern_pdf_config = True -``` - -#### Update the copyright - -The Ulwazi theme expects a plain year string rather than the older {spellexception}`CC-BY-SA` format. - -```{code-block} python -:caption: conf\.py - -copyright = f"{datetime.date.today().year}" -``` - -The license information is now conveyed through the "license" key in "html_context". - -## Test the documentation - -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 -make clean -make run -``` - -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). diff --git a/docs/explanation/assets/components.yaml b/docs/explanation/assets/components.yaml deleted file mode 100644 index 4918b05c..00000000 --- a/docs/explanation/assets/components.yaml +++ /dev/null @@ -1,68 +0,0 @@ -# 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." - mermaid_code: | - graph LR - 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: "sphinx.png" - - - diagram_name: "Python environment" - description: "The relationship between the host system and the virtual environment." - mermaid_code: | - graph LR - subgraph Host ["Host"] - direction LR - pip[pip] -->|installs| PD["Project dependencies"] - python3[python3] --> Sphinx - venv[venv] -->|creates| VE["Virtual environment"] - subgraph VE ["Virtual environment"] - direction LR - PD -->|extend| Sphinx - end - Sphinx -->|builds| HTML[HTML] - end - 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." - mermaid_code: | - graph TD - Python -->|installs the contents of| Reqs[/"requirements.txt"\] - Reqs -->|specifies| ThirdParty["Third-party extensions"] - Sphinx -->|provides| BuiltIn["Built-in Sphinx extensions"] - subgraph Deps ["Various dependencies"] - BuiltIn - ThirdParty - end - BuiltIn -->|are activated in| Conf[/"Project configuration file (docs/conf.py)"\] - ThirdParty -->|are activated in| Conf - rendered_image: "extensions.png" - - - diagram_name: "Read the Docs" - description: "Details the declaration of build logic in the RTD configuration file for hosting." - mermaid_code: | - graph TD - Sphinx -->|is declared in| RTD_Conf[/"RTD configuration file (.readthedocs.yaml)"\] - Conf_py["conf.py"] -->|is declared in| RTD_Conf - 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: "rtd-build.png" - - - diagram_name: "Third-party extensions" - description: "Focuses on the specific installation path for external dependencies via pip and requirements." - mermaid_code: | - graph TD - Python[Python] - Reqs[/"requirements.txt"\] - Sphinx[Sphinx] - subgraph Deps ["Various dependencies"] - BuiltIn["Built-in Sphinx extensions"] - ThirdParty["Third-party extensions"] - end - Python -->|installs the contents of| Reqs - Reqs -->|specifies| ThirdParty - rendered_image: "third-party-extensions.png" \ No newline at end of file diff --git a/docs/explanation/assets/extensions.png b/docs/explanation/assets/extensions.png deleted file mode 100644 index 182275c7..00000000 Binary files a/docs/explanation/assets/extensions.png and /dev/null differ diff --git a/docs/explanation/assets/python-starter-pack.png b/docs/explanation/assets/python-starter-pack.png deleted file mode 100644 index 5aece070..00000000 Binary files a/docs/explanation/assets/python-starter-pack.png and /dev/null differ diff --git a/docs/explanation/assets/rtd-build.png b/docs/explanation/assets/rtd-build.png deleted file mode 100644 index e423a6ba..00000000 Binary files a/docs/explanation/assets/rtd-build.png and /dev/null differ diff --git a/docs/explanation/assets/sphinx.png b/docs/explanation/assets/sphinx.png deleted file mode 100644 index 710fbe59..00000000 Binary files a/docs/explanation/assets/sphinx.png and /dev/null differ diff --git a/docs/explanation/assets/third-party.png b/docs/explanation/assets/third-party.png deleted file mode 100644 index f7720999..00000000 Binary files a/docs/explanation/assets/third-party.png and /dev/null differ diff --git a/docs/explanation/build.rst b/docs/explanation/build.rst deleted file mode 100644 index 1fb8ce7b..00000000 --- a/docs/explanation/build.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. meta:: - :description: Learn about the function, structure, and design of the build process in Canonical's Starter Pack. - -:relatedlinks: [GNU Make](https://www.gnu.org/software/make/) - - -.. _build: - -Build -====== - -Canonical's Starter Pack 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``. - -Make is also the user interface for operating a project's docs. Authors and developers -call all docs actions with ``make ``. - -The docs build depends on environment variables like ``BUILDDIR`` to locate critical -files. They are conditional variables, so other systems can invoke the build at -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 -down and rebuilds it. - - -.. _explanation-parent-project-build: - -Parent projects and the build ------------------------------ - -The Starter Pack 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 -parallel with the parent build. When embedded, the virtual environment and build recipe -files would be arranged along these lines: - -.. code-block:: - - Project - │ - ├── ... - ├── docs - │ ├── ... - │ ├── .venv - │ └── Makefile - ├── src - │ └── ... - ├── - └── - -With embedded docs, the parent build doesn't mesh with the docs build, which can cause -difficulty: - -- Contributors typically call the build commands from the root of the project. Some will - find it inconvenient to run the docs commands by switching to the ``docs`` directory - 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`` - 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. - -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 -update, requiring a rewrite of the parent build recipes. - -The solution to these complications is to create a bridge between the two builds, from -the parent build to the docs ``Makefile``. -:ref:`bridge-project-and-docs-builds` is a guide for how to do this. diff --git a/docs/explanation/components.rst b/docs/explanation/components.rst deleted file mode 100644 index 79b402ea..00000000 --- a/docs/explanation/components.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. meta:: - :description: A breakdown of Canonical's Sphinx Starter Pack that covers its constituent elements and their purpose. - -.. _explanation-structure: - -Starter Pack structure -======================= - -The Starter Pack is a template `Sphinx `__ -project. It provides a default file structure, a theme, and dependencies for Canonical -documentation. - - -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. - -``docs/conf.py`` 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 - - Sphinx as a documentation static site generator - - -Python ------- - -Because Sphinx is a Python application, the Starter Pack 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 -system. - -To be able to work on a Starter Pack project, your host needs Python 3.11, pip, and venv. - -.. figure:: assets/python-starter-pack.png - :class: with-border - - Python's role in the Starter Pack - - -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. - -.. figure:: assets/extensions.png - :class: with-border - - Extension types - - -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. - - -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 -`requirements.txt `__ -file. - -.. figure:: assets/third-party.png - :class: with-border - - Third-party extensions - - -Markdown support -^^^^^^^^^^^^^^^^ - -By default, Sphinx uses reStructuredText. Markdown is supported through the `MyST parser -`_, which is enabled with the -``myst-parser`` extension. - - -Canonical theme -^^^^^^^^^^^^^^^ - -The Canonical theme is packaged as a standalone `canonical-sphinx -`_) extension. It is based on `Furo -`__ and is designed to follow Canonical branding. - - -Command-line tools ------------------- - -The Starter Pack uses Make as its local build system. The Starter Pack's Makefile -provides a command-line interface for setting up the virtual environment, installing -dependencies, building the documentation, and more. - - -Makefile -~~~~~~~~ - -Some of the Makefile targets (such as ``html`` and ``linkcheck``) provide Sphinx-native -functionality for building documentation or performing tests in a simplified form while -managing required dependencies. For example, instead of using the ``sphinx-build -linkcheck SOURCEDIR OUTPUTDIR`` command, you can use ``make linkcheck``. - -See :ref:`build` to learn how the local build process works. - -Additionally, the Makefile provides commands to trigger third-party CLI tools, such as -the Vale prose linter for :ref:`Style guide linting `. - - -Read The Docs configuration file --------------------------------- - -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 -``.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. - -.. figure:: assets/rtd-build.png - :class: with-border - - Read the Docs build configuration - diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index e4a11125..f8ded01b 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,20 +1,4 @@ -.. meta:: - :description: Explore topics about the concepts and ideas in Canonical's Starter Pack. - - .. _explanation: Explanation =========== - -Explore topics about the concepts and ideas in Canonical's Starter Pack. - -The Starter Pack is built using standard Python tools, and is both deep and flexible. - -.. toctree:: - :maxdepth: 1 - - components - build - sitemaps - diff --git a/docs/explanation/sitemaps.rst b/docs/explanation/sitemaps.rst deleted file mode 100644 index d588d2c2..00000000 --- a/docs/explanation/sitemaps.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. meta:: - :description: An in-depth look at the sitemaps feature in the Starter Pack, including configuration, validation, and versioning. - -.. _sitemaps: - -Sitemaps -========= - -The latest version of the Starter Pack 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. - -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. - -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 -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``. - -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`): - -.. code-block:: - - extensions = ['sphinx_sitemap'] - -Sitemap configuration -^^^^^^^^^^^^^^^^^^^^^ - -The Starter Pack's configuration file (:file:`docs/conf.py`) includes default sitemap configuration. - -The ``sphinx-sitemap`` extension requires a ``html_baseurl`` variable to be configured. - -This is set by default as follows: - -.. 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). - -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. - -.. 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. - - 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As of version 2.7.0, the sitemap extension supports adding a ``lastmod`` date. -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`:: - - sitemap_excludes = [ - '404/', - 'genindex/', - 'search/', - ] - -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. - -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: - -* 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. - -Support multiple versions -------------------------- - -The sphinx-sitemap extension doesn't support multiple versions by default. Configuring -your versioned documentation to use an appropriate version may be sufficient, as search -engines and other web systems crawl websites for the purposes of indexing. - -If you want sitemaps for all your documentation's versions, you need to deploy your own -``robots.txt`` file and sitemap index. Supporting multiple versions is recommended for -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 -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 -extension with the appropriate version. - -Next, create a ``sitemapindex.xml`` file in the same directory as the configuration -file, and point to the sitemap files of each of your documentation sets: - -.. code-block:: xml - :caption: sitemapindex.xml - - - - https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/3.0/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/2.0/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/1.0/sitemap.xml - - - -Create a ``robots.txt`` file in the same directory as the configuration file. - -If necessary, block any paths you don't want crawled. Google describes how to do this in -`How to write and submit a robots.txt file -`__. - -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 - -Lastly, add both new files to the configuration file: - -.. code-block:: - :caption: conf.py - - html_extra_path = [ - "sitemapindex.xml", - "robots.txt", - ] - -This provides a ``sitemapindex.xml`` file which points to the ``sphinx-sitemap`` -generated sitemap for each version. - -You may want to automate the generation of the ``sitemapindex.xml`` file. To see how -this is done for the Ubuntu documentation library project, which generates a sitemap -containing subproject sitemaps, see `the script here -`_. diff --git a/docs/how-to/assets/mermaid.txt b/docs/how-to/assets/mermaid.txt deleted file mode 100644 index 68ec1b56..00000000 --- a/docs/how-to/assets/mermaid.txt +++ /dev/null @@ -1,313 +0,0 @@ -mermaid-diagram-flowchart-start -``````{tab-set} - -`````{tab-item} Diagram -```{image} https://assets.ubuntu.com/v1/34c7105c-screenshot_from_2025_10_13_15_05_56.png -``` -````` - -`````{tab-item} MyST - -````{code-block} md -```{mermaid} -flowchart LR - A([New PR]) - B[Needs review] - C{Review approved?} - D{Merge conflicts?} - E[Needs work] - F[Needs CI] - G{Passed testing?} - H[Ready for merge] - I[(PR merged)] - J{Comments addressed?} - K[(PR closed)] - - A --> B - B --> C - C -- no --> E - C -- yes --> D - D -- yes --> E - D -- no --> F - F --> G - G -- yes --> H - G -- no --> E - H --> I - E --> J - J -- yes --> B - J -- no --> K -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -.. mermaid:: - - flowchart LR - A([New PR]) - B[Needs review] - C{Review approved?} - D{Merge conflicts?} - E[Needs work] - F[Needs CI] - G{Passed testing?} - H[Ready for merge] - I[(PR merged)] - J{Comments addressed?} - K[(PR closed)] - - A --> B - B --> C - C -- no --> E - C -- yes --> D - D -- yes --> E - D -- no --> F - F --> G - G -- yes --> H - G -- no --> E - H --> I - E --> J - J -- yes --> B - J -- no --> K -```` - -````` -`````` -mermaid-diagram-flowchart-end - -mermaid-diagram-sequence-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/a7eb0fcf-screenshot_from_2025_10_13_15_08_06.png -``` - -````` - -`````{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`. - -Then, enable custom stylesheets in {file}`conf.py`. -Uncomment this line so Sphinx can use local stylesheets: - -```{code-block} py -:caption: conf\.py - -html_static_path = ["_static"] -``` - -Link to your custom Mermaid stylesheet: - -```{code-block} py -:caption: conf\.py - -html_css_files = [ - "mermaid-sequence.css", -] -``` - -Here's an example stylesheet that changes the default typefaces and colors of Mermaid components. -It also sets a solid background color for all Mermaid diagrams. - -```{code-block} css -:caption: mermaid-sequence.css - -.actor { - stroke: #eb6536 !important; - stroke-width: 2; - fill: #f5b29b !important; -} - -text.actor { - fill: black; - stroke: none; - font-family: Helvetica; -} - -.actor-line { - stroke: #77216f; -} - -.mermaid { - background-color: #f0f0f0; - border: 1px solid #ccc; - border-radius: 6px; - padding: 0.5em; -} -``` -````` - -`````{tab-item} MyST - -````{code-block} md -```{mermaid} -sequenceDiagram - participant User - participant Snap as snapd (Client) - participant Store as Snap Store - participant System - - User->>Snap: snap install hello - Snap->>Store: Request snap info and download - Store-->>Snap: Return snap package - Snap->>System: Install and mount snap - System-->>Snap: Installation result - Snap-->>User: Confirm snap is installed -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -.. mermaid:: - - sequenceDiagram - participant User - participant Snap as snapd (Client) - participant Store as Snap Store - participant System - - User->>Snap: snap install hello - Snap->>Store: Request snap info and download - Store-->>Snap: Return snap package - Snap->>System: Install and mount snap - System-->>Snap: Installation result - Snap-->>User: Confirm snap is installed -```` - -````` -`````` -mermaid-diagram-sequence-end - -mermaid-diagram-timeline-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/24895eed-screenshot_from_2025_10_13_15_06_35.png -``` - -````` - -`````{tab-item} MyST - -````{code-block} md -:emphasize-lines: 2 -```{mermaid} -%%{init: {"theme":"forest"}}%% -timeline - title Ubuntu recent releases - - 2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla) - 2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri) - 2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu) - 2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur) - 2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole) - 2025 : 25.04 (Plucky Puffin) -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -:emphasize-lines: 3 - -.. mermaid:: - - %%{init: {"theme":"forest"}}%% - timeline - title Ubuntu recent releases - - 2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla) - 2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri) - 2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu) - 2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur) - 2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole) - 2025 : 25.04 (Plucky Puffin) -```` - -````` -`````` -mermaid-diagram-timeline-end - -mermaid-diagram-state-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/dd4fb237-screenshot_from_2025_10_13_15_08_51.png -``` - -````` - -`````{tab-item} MyST - -````{code-block} md -:emphasize-lines: 3-6, 17-20 - -```{mermaid} -stateDiagram-v2 - classDef review fill:#FCE83A - classDef approved fill:#2DCCFF - classDef published fill:#56F000 - classDef archived fill:#7B8089 - - [*] --> Draft - Draft --> Review : submit for review - Review --> Draft : changes requested - Review --> Approved : review passed - Approved --> Build : trigger build - Build --> Published : build success - Build --> Draft : build failed - Published --> Archived : old version - - class Review review - class Approved approved - class Published published - class Archived archived -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -:emphasize-lines: 4-7, 18-21 - -.. mermaid:: - - stateDiagram-v2 - classDef review fill:#FCE83A - classDef approved fill:#2DCCFF - classDef published fill:#56F000 - classDef archived fill:#7B8089 - - [*] --> Draft - Draft --> Review : submit for review - Review --> Draft : changes requested - Review --> Approved : review passed - Approved --> Build : trigger build - Build --> Published : build success - Build --> Draft : build failed - Published --> Archived : old version - - class Review review - class Approved approved - class Published published - class Archived archived -```` - -````` -`````` -mermaid-diagram-state-end \ No newline at end of file diff --git a/docs/how-to/assets/openapi._rst b/docs/how-to/assets/openapi._rst deleted file mode 100644 index 396913a9..00000000 --- a/docs/how-to/assets/openapi._rst +++ /dev/null @@ -1,22 +0,0 @@ -.. raw:: html - - -
- - - \ No newline at end of file diff --git a/docs/how-to/assets/openapi.yaml b/docs/how-to/assets/openapi.yaml deleted file mode 100644 index 4e53d08c..00000000 --- a/docs/how-to/assets/openapi.yaml +++ /dev/null @@ -1,24 +0,0 @@ -openapi: 3.0.3 -info: - title: Hello API - version: 1.0.0 -paths: - /hello: - get: - summary: Say hello - parameters: - - in: query - name: name - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: "Hello, world!" diff --git a/docs/how-to/assets/troubleshoot-stable-zombie-version.png b/docs/how-to/assets/troubleshoot-stable-zombie-version.png deleted file mode 100644 index 624aac1a..00000000 Binary files a/docs/how-to/assets/troubleshoot-stable-zombie-version.png and /dev/null differ diff --git a/docs/how-to/build-and-preview.rst b/docs/how-to/build-and-preview.rst deleted file mode 100644 index fce9147c..00000000 --- a/docs/how-to/build-and-preview.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. meta:: - :description: How to set up your environment and use make commands to build and preview documentation locally. - -.. _build-and-preview: - -Build and preview -================= - -The Starter Pack provides a :file:`Makefile` that defines :command:`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. - -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. - -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 - -Python environment ------------------- - -The Python prerequisites from the :file:`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 from within your documentation folder:: - - make install - -This command creates a virtual environment (:file:`.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 from within your documentation folder:: - - 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`` - - -.. important:: - Run these commands from within your documentation folder. - -.. _build-docs: - -Build the documentation ------------------------ - -To build the documentation, run the following command:: - - make html - -This command installs the required tools and renders the output to the :file:`_build/` folder in your documentation folder. - -.. 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`. - -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:: - - make clean-doc html - -To delete both the existing output files and the Python environment and build the full documentation again, run the following command:: - - make clean html - -View the documentation ----------------------- - -To view the documentation output, run the following command:: - - make serve - -This command builds the documentation and serves it on :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:: - - 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. - -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/" - -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) -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. - - 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 - - make pdf - -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: - -* dvipng -* fonts-freefont-otf -* latexmk -* plantuml -* tex-gyre -* texlive-font-utils -* texlive-fonts-recommended -* texlive-lang-cjk -* texlive-latex-extra -* texlive-latex-recommended -* texlive-xetex -* xindy - -On Linux, required packages can be installed with: - -.. code-block:: none - - make pdf-prep-force - -.. note:: - - 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. - - 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 deleted file mode 100644 index b9d99b72..00000000 --- a/docs/how-to/configure-your-project.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. meta:: - :description: How to configure project-specific parameters. - -.. _configure-your-project: - -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. - -.. important:: - - After setting up your repository with the Starter Pack, you should track the changes made to the Starter Pack. - - 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. - -Configuration for a Starter Pack based documentation is set in the :file:`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. - -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. - -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. - -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. - -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. - -Modify the template -~~~~~~~~~~~~~~~~~~~ - -The default Starter Pack 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. - -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. - -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 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 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``. - -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 -~~~~~~~~~~~~~ - -If you rename a source file, its URL will change. To prevent broken links, you should -add a redirect from the old URL to the new URL in this case. - -You can add redirects in the ``docs/redirects.txt`` file. The paths for internal -redirects are relative to the root of the docs project. - -.. code-block:: - - "path/to/old/page" "path/to/new/page" - -Destination paths can also be external URLs. - -.. code-block:: - - "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 ``canonical_sphinx`` extension is required for the Starter Pack 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`. - -.. 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. - -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. - -.. code:: python - - 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). - -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|:: - - :sequential_nav: both - - [Page contents] - -MyST:: - - --- - sequential_nav: both - --- - - [Page contents] - -Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the :file:`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 `_. - -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. - -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) - -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``. diff --git a/docs/how-to/contributing-myst.md b/docs/how-to/contributing-myst.md deleted file mode 100644 index 2efcd9c6..00000000 --- a/docs/how-to/contributing-myst.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -myst: - html_meta: - description: How to contribute code, documentation, and tests to the Starter Pack. -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 82f97354..00000000 --- a/docs/how-to/contributing.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. meta:: - :description: How to contribute code, documentation, and tests to the Starter Pack. - -: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 7050375e..d7a5b154 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -1,44 +1,4 @@ -.. meta:: - :description: Explore the essential guides and procedures in Canonical's Starter Pack. - - .. _how-to-guides: How-to guides ============= - -These guides will walk you through the processes involving setting up, -maintaining, and contributing to the Starter Pack. - -Basic setup and maintenance ---------------------------- - -Set up, configure, update, and customize your project to keep it organized and aligned with -your documentation needs. - -.. toctree:: - :maxdepth: 1 - - configure-your-project - build-and-preview - run-documentation-checks - publish-on-rtd - update-starter-packs/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. - -While some of these features are available by default in the Starter Pack, others may require additional -extensions. - -The following guides will help you get started: - -.. toctree:: - :maxdepth: 2 - - optional-customisation/index.rst diff --git a/docs/how-to/optional-customisation/add-documentation-testing.rst b/docs/how-to/optional-customisation/add-documentation-testing.rst deleted file mode 100644 index d89b6511..00000000 --- a/docs/how-to/optional-customisation/add-documentation-testing.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. meta:: - :description: How to use Spread to automatically test commands in documentation and keep them in sync with your product. - -.. _how-to-add-documentation-testing: - -Use Spread to test commands in documentation -============================================ - -It's challenging to keep documentation in sync with products as they evolve. This -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. - -What you'll need ----------------- - -* `Multipass `_ installed on your machine -* `Spread `_ installed on your machine - -.. warning:: - - Spread requires elevated permissions to run as root. Use the - `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: - -.. code-block:: yaml - :caption: project_name/spread.yaml - - project: project_name - - path: /project_name - -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``: - -.. code-block:: yaml - :caption: project_name/spread.yaml - :emphasize-lines: 5-9 - - project: project_name - - path: /project_name - - suites: - tests/spread/: - summary: example test - 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``. - -Set up the Multipass backend ----------------------------- - -Each job in Spread has a backend, or a way to obtain a machine for running your Spread -tests. Spread can run on various backends, like -`Google `__, -`QEMU `__, or, as this -guide sets up, Multipass. - -Copy the following ``backends`` section of ``spread.yaml`` between the ``path`` and -``suites`` sections: - -.. code-block:: yaml - :caption: project_name/spread.yaml - :emphasize-lines: 5-40 - - project: project_name - - path: /project_name - - backends: - multipass: - type: adhoc - allocate: | - multipass_image=24.04 - instance_name="example-multipass-vm" - - # Launch Multipass VM - multipass launch --cpus 2 --disk 10G --memory 2G --name "${instance_name}" "${multipass_image}" - - # Enable PasswordAuthentication for root over SSH. - multipass exec "$instance_name" -- \ - sudo sh -c "echo root:${SPREAD_PASSWORD} | sudo chpasswd" - multipass exec "$instance_name" -- \ - sudo sh -c \ - "if [ -d /etc/ssh/sshd_config.d/ ] - then - echo 'PasswordAuthentication yes' > /etc/ssh/sshd_config.d/10-spread.conf - echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config.d/10-spread.conf - else - sed -i /etc/ssh/sshd_config -E -e 's/^#?PasswordAuthentication.*/PasswordAuthentication yes/' -e 's/^#?PermitRootLogin.*/PermitRootLogin yes/' - fi" - multipass exec "$instance_name" -- \ - sudo systemctl restart ssh - - # Get the IP from the instance - ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3) - ADDRESS "$ip" - - discard: | - instance_name="example-multipass-vm" - multipass delete --purge "${instance_name}" - - systems: - - ubuntu-24.04-64: - workers: 1 - - suites: - tests/spread/: - summary: example test - systems: - - ubuntu-24.04-64 - -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``. - -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. - -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: - -.. code-block:: yaml - :caption: task.yaml - - summary: Example Spread test - - kill-timeout: 5m - - prepare: | - echo "Use this section to install any prerequisites" - - execute: | - echo "This is the first command that Spread will run" - - 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. - -.. note:: - - 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. - -For example, consider the following ``task.yaml`` file: - -.. code-block:: yaml - :caption: task.yaml - - summary: Clone and build the Starter Pack - - 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:build-documentation] - cd sphinx-docs-starter-pack/docs - make run - # [docs:build-documentation-end] - -Include the commands from ``task.yaml`` in your documentation with: - -.. tab-set:: - - .. tab-item:: reStructuredText - :sync: rest-commands - - .. code-block:: rst - :caption: Example ``literalinclude`` blocks - - Clone the Starter Pack: - - .. literalinclude:: relative-path-to/task.yaml - :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] - :dedent: 2 - - Enter the ``docs`` folder and build the project: - - .. literalinclude:: relative-path-to/task.yaml - :language: bash - :start-after: [docs:build-documentation] - :end-before: [docs:build-documentation-end] - :dedent: 2 - - .. tab-item:: MyST - :sync: myst-commands - - .. code-block:: md - :caption: Example ``literalinclude`` blocks - - Clone the Starter Pack: - - ```{literalinclude} relative-path-to/task.yaml - :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] - :dedent: 2 - ``` - - Enter the `docs` folder and build the project: - - ```{literalinclude} relative-path-to/task.yaml - :language: bash - :start-after: [docs:build-documentation] - :end-before: [docs:build-documentation-end] - :dedent: 2 - ``` - -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. - -Run tests locally ------------------ - -List all available Spread tests in the code repository: - -.. code-block:: bash - - spread --list - -The terminal should respond with all the tests defined in ``spread.yaml``. -For example: - -.. terminal:: - :dir: project_name - - spread --list - - 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: - -.. code-block:: bash - - spread -vv -debug multipass:ubuntu-24.04-64:tests/spread/example_documentation_test - -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 ------------------ - -During runtime, the terminal outputs various messages about allocating the Multipass VM, -connecting to the VM, sending the Spread test to the VM and executing the test. -If the test is successful, the terminal will output something similar to the following: - -.. terminal:: - :output-only: - - 2025-02-04 16:17:10 Successful tasks: 1 - 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: - -.. terminal:: - :dir: project_name - - multipass list - - 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: - -.. terminal:: - :output-only: - - 2025-02-04 16:17:10 Starting shell to debug... - 2025-02-04 16:17:10 Sending script for multipass:ubuntu-24.04-64 (multipass:ubuntu-24.04-64:tests/spread/example_documentation_test): - - -.. _ReStructuredText (.rst): https://www.sphinx-doc.org/en/master/usage/restructuredtext -.. _MyST-Markdown: https://myst-parser.readthedocs.io/en/latest 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 deleted file mode 100644 index 469c3ea3..00000000 --- a/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst +++ /dev/null @@ -1,355 +0,0 @@ -.. meta:: - :description: How to bridge the build of Canonical's Starter Pack 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) - - -.. _bridge-project-and-docs-builds: - -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 -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. - -:ref:`explanation-parent-project-build` describes the full benefits of bridging the -build in a larger project. - - -.. _how-to-bridge-project-builds-project-requirements-layout: - -Plan and requirements ---------------------- - -The bridge is built by making up to three changes to the build. - -The bridge **shims the docs build targets in the main build**. Any build system is -capable of adding targets that call other systems. When shimmed, the docs targets like -``html`` and ``clean`` pass through to ``docs/Makefile``, with arguments. - -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 -dependency manager will do, and this guide illustrates with three: - -- pip 25.1 and higher -- uv 0.4.27 and higher -- Poetry 1.2.0a2 and higher - -After adding the bridge, it's also possible to **adjust the documentation workflows** to -use your project's main build. The workflows were designed with Make, so they only work -if you use it for your build system. - - -Example project layout ----------------------- - -This guide illustrates the bridge through an example project. In the example project, -the file tree contains: - -.. code-block:: - - Project - │ - ├── ... - ├── docs - │ └── Makefile - ├── .venv - ├── Makefile - └── pyproject.toml - -The example project's root ``Makefile`` has two conventional targets that need -adjustment: - -- ``setup`` for building the virtual environment and syncing dependencies -- ``clean`` for cleaning up the virtual environment and temporary files - - -.. _how-to-bridge-project-builds-set-docs-env-vars: - -Set the build paths -------------------- - -Where your main build sets environment variables, redeclare the docs environment -variables that specify the build paths: - -- ``DOCS_BUILDDIR`` is the destination for the docs. If you have special distribution - needs you can override this, but for most builds this can be left as-is. -- ``DOCS_VENVDIR`` is the virtual environment of the docs. If you're merging the virtual - environments, set this as a relative path from the docs directory to your project's - virtual environment. -- ``VALE_DIR`` is the path to the Vale binary. The full path depends on the - location of your virtual environment, so it's best to copy this as-is. - -In the example project, this looks like: - -.. code-block:: make - :caption: Makefile - - # Env vars for the docs build - export DOCS_BUILDDIR ?= _build - export DOCS_VENVDIR ?= ../.venv - export VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale - - -.. _how-to-bridge-project-builds-integrate-docs-setup: - -Integrate the docs setup ------------------------- - -The next step is to incorporate the docs installation target, and optionally the -dependencies, into the main build. - - -Separate virtual environments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you don't plan to merge the virtual environments, override the installation target by -calling all three doc installation targets in a row. - -In the example project, this is written as: - -.. code-block:: make - :caption: Makefile - - # Override the - .PHONY: docs-install - docs-install: - $(MAKE) -C docs install --no-print-directory - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - -Merged virtual environments -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To merge virtual environments, the ``setup`` target must handle both development and -docs packages, and enumerate all docs packages in ``pyproject.toml``. Your project will -also need dependency groups to organize the packages. The result will be one virtual -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 - -First, add the dependency groups. The docs group should depend on the Starter Pack -group: - -.. code-block:: toml - :caption: pyproject.toml - - [dependency-groups] - dev = [ - # Packages for main development and testing - ] - docs = [ - # Packages for extra docs features - {include-group = "docs-starter-pack"}, - ] - docs-starter-pack = [ - # Core docs packages - ] - -If your ``pyproject.toml`` file didn't already have a ``dev`` dependency group, review the -packages listed in the ``dependencies`` key, then move any non-runtime dependencies to -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. - -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 -the example project, it's written like this: - -.. tabs:: - - .. tab:: pip - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - pip install --group dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - pip install --group docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - .. tab:: uv - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - uv sync --group dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - uv sync --no-dev --group docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - .. tab:: Poetry - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - poetry install --only dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - poetry install --only docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - -If your docs aren't written in Markdown, remove the command that runs the -``pymarkdownlnt-install`` target. - - -.. _how-to-bridge-project-builds-shim-remaining-targets: - -Shim the remaining targets --------------------------- - -The docs build has many targets, but only a handful of them overlap or collide with most -project builds, so we only need to override two more. The rest can pass straight through -to the docs build. - -In the example project, the main build calls the targets like this: - -.. code-block:: make - :caption: Makefile - - # Override for `clean` target in docs project. We don't want to touch `.venv`, - # so we pass a temp dir instead. - .PHONY: docs-clean - docs-clean: - DOCS_VENVDIR=$(mktemp) $(MAKE) -C docs clean --no-print-directory - - # Override for `help` target - .PHONY: docs-help - docs-help: - @echo "Commands in the documentation subproject:" - $(MAKE) -C docs help --no-print-directory - @echo "Run these commands with 'make docs-' in the project root." - - # Shim for the rest of the targets in docs Makefile - .PHONY: docs-% - docs-%: docs-install - $(MAKE) -C docs $(@:docs-%=%) --no-print-directory - -.. admonition:: Variables and Makefiles - - 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 - them, you must set them explicitly with `export` or as as command-line arguments. - - For example, within the main build, if you need to customize - ``SPHINX_AUTOBUILD_OPTS``, pass it to the docs build like this: - - .. code-block:: make - :caption: Makefile - - $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" - -.. _how-to-bridge-project-builds-adjust-rtd-build: - -Adjust the Read the Docs build ------------------------------- - -With the Makefile in a different location than usual, and its being a separate process, -it's simplest to override the Read the Docs build in ``.readthedocs.yaml`` to call the -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. - -Here's what it looks like in the example project: - -.. code-block:: yaml - :caption: .readthedocs.yaml - :emphasize-lines: 8-14 - - build: - os: ubuntu-24.04 - tools: - python: "3.12" - jobs: - post_checkout: - - git fetch --tags --unshallow # Also fetch tags - create_environment: - - python3 -m venv "${READTHEDOCS_VIRTUALENV_PATH}" - install: - - make docs-install DOCS_VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" - build: - html: - - make docs DOCS_VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" DOCS_BUILDDIR="$READTHEDOCS_OUTPUT/html/" - - -.. _how-to-bridge-project-builds-adjust-doc-workflows: - -Adjust the doc workflows ------------------------- - -If your project uses the Starter Pack's docs 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 -`_: - -.. code-block:: yaml - :caption: .github/workflows/automatic-doc-checks.yml - :emphasize-lines: 5, 7-11 - - jobs: - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: "." - fetch-depth: 0 - install-target: docs-install - spelling-target: docs-spelling - woke-target: docs-woke - linkcheck-target: docs-linkcheck - pa11y-target: docs-pa11y - -If your docs are written in Markdown, override the path and command inputs in the -Markdown linter workflow: - -.. code-block:: yaml - :caption: .github/workflows/markdown-style-checks.yml - :emphasize-lines: 2-6 - - - name: Create venv - working-directory: "." - run: make docs-install - - name: Lint markdown - working-directory: "." - run: make docs-lint-md diff --git a/docs/how-to/optional-customisation/custom-html-templates.md b/docs/how-to/optional-customisation/custom-html-templates.md deleted file mode 100644 index ec7c8198..00000000 --- a/docs/how-to/optional-customisation/custom-html-templates.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -myst: - html_meta: - description: How to extend or override default HTML templates to customize documentation structure and layout. ---- - -(custom-html-templates)= - -# 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. - -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. - -```{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. -``` - -## Setup - -First, create the {file}`docs/_templates` directory; all your custom templates will need to be stored in this folder. - -Then uncomment this line in {file}`docs/conf.py` so your project will use local templates (where available): - -```{code-block} py -:caption: conf\.py - -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. - - -```{seealso} -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. - -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. - -```{code-block} html -:caption: page.html -:emphasize-lines: 3-14 -:class: no-copybutton - -{% block right_sidebar %} -
- {% if not furo_hide_toc_orig %} -
- - {{ _("Contents") }} - -
-
-
- {{ toc }} -
-
- {% endif %} - {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} -
- -``` - -### 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. - -Then modify the conditional statement related to the GitHub URL with your code. - -```{code-block} html -:caption: header.html -:emphasize-lines: 5-13 - -[...] - {% if github_url %} -
  • - - - - - - GitHub - -
    • - {% endif %} -[...] -``` - -## 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`. - -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. - -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. - -```{code-block} html -:emphasize-lines: 2-6 -:caption: _templates/page.html - -{% block body -%} - {% if pagename in ["how-to/build", "how-to/custom-templates"] %} - {% include "special-header.html" %} - {% else %} - {% include "header.html" %} - {% endif %} - {{ super() }} -{%- endblock body %} -``` - -### 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. - -```{code-block} html -:caption: _templates/page.html - -{% if pagename in ["how-to/customise", "how-to/diagrams-as-code"] %} - {% extends "special-page.html" %} -{% else %} - {% extends "furo/page.html" %} -{% endif %} -``` - -```{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`. -``` - -% LINKS -[canonical-sphinx theme]: https://github.com/canonical/canonical-sphinx/tree/main/canonical_sphinx/theme/templates -[Jinja template syntax reference]: https://jinja.palletsprojects.com/en/latest/templates/ -[page.html]: https://github.com/canonical/canonical-sphinx/blob/main/canonical_sphinx/theme/templates/page.html -[header.html]: https://github.com/canonical/canonical-sphinx/blob/main/canonical_sphinx/theme/templates/header.html diff --git a/docs/how-to/optional-customisation/customise-pdf.rst b/docs/how-to/optional-customisation/customise-pdf.rst deleted file mode 100644 index 6125e978..00000000 --- a/docs/how-to/optional-customisation/customise-pdf.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. meta:: - :description: How to customize PDF output with LaTeX. - -.. _pdf-customise: - -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. - -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. - -This guide covers common practices and tips for customising PDF output from your project using the Starter Pack 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: - -.. 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. -* ``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. - -* ``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. - - -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. - -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: - -.. code-block:: python - - 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. - -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. - -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`: - - .. code-block:: python - - # Identify the Sphinx builder being used - if '-b' in sys.argv: - builder = sys.argv[sys.argv.index('-b') + 1] - elif '-M' in sys.argv: - builder = sys.argv[sys.argv.index('-M') + 1] - else: - builder = 'html' # default builder - - # Exclude the PDF-specific index from the HTML build - if builder in ['html', 'dirhtml']: - exclude_patterns.append('pdf-index.rst') - -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``. - - -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. - -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 documentation project directory. For example, at :file:`_dev/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. - -.. code-block:: python - - # 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. - - -Add more LaTeX packages to the preamble -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 - - { - ... - '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. - - -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. - -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 - - { - ... - '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. - -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. - -.. code-block:: python - - # 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. - - -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. - -1. 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}', - ... - } - - .. 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. - - 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 - - \begin{landscape} - - .. list-table:: Example of a landscape table - :header-rows: 1 - - * - Column 1 - - Column 2 - - Column 3 - * - Data 1 - - Data 2 - - Data 3 - - .. only:: latex - - .. raw:: latex - - \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. - -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. - -.. warning:: - - 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 deleted file mode 100644 index ba1782fb..00000000 --- a/docs/how-to/optional-customisation/enable-google-analytics.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. meta:: - :description: How to enable Google Analytics in your project. - -.. _how-to-enable-google-analytics: - -Enable Google Analytics -======================= - -Many documentation sites collect page view and user behavior data with Google Analytics. -Collecting this data requires the user's consent. - -Once you're through with the guide, analytics will be collected on all public versions -of your documentation. - - -Add or update templates ------------------------ - -The header template inserts the Google Analytics tracking tag onto each page. If a user -consents to being tracked, their traffic and search data will be collected with each -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/_dev/version`` file. - - -On Starter Pack 1.6 or higher -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting in version 1.6 of the Starter Pack, 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In version 1.5 of the Starter Pack and lower, the templates were sourced from a separate -repository. - -Download the latest version of the templates: - -- :literalref:`header.html ` -- :literalref:`footer.html ` - -Next, create a ``docs/_templates`` directory and move the templates into it. - -If you find that your project already has a ``header.html`` file, add the following HTML -immediately after the opening ``
    `` tag: - -.. code-block:: html - - - - -Similarly, if your project already has a ``footer.html`` file, add the following -highlighted line to the ``right-details`` div: - -.. code-block:: html - :emphasize-lines: 2 - -
    - Manage your tracker settings -
    - - -.. _update-your-configuration-file: - -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 -in your configuration file. You only need to uncomment them in the following steps. In -lower versions, you need to add them yourself. - -Add or uncomment the following line: - -.. code-block:: python - :caption: conf.py - - templates_path = ["_templates"] - -The script and style sheet for the cookie banner are hosted remotely. Include them -in your docs by adding or uncommenting the following lines in the ``conf.py`` file: - -.. code-block:: python - :caption: conf.py - - html_css_files = ["https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css"] - - html_js_files = ["https://assets.ubuntu.com/v1/287a5e8f-bundle.js"] - - -Test the cookie banner ----------------------- - -To verify that everything is working, run the following commands in the ``docs/`` -directory: - -.. code-block:: bash - - make clean - make install - make run - -You may need to clear your browser cache for changes to take effect. diff --git a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst b/docs/how-to/optional-customisation/external-referencing-intersphinx.rst deleted file mode 100644 index 72c6b1d5..00000000 --- a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. meta:: - :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. - -Configure the extension ------------------------ - -In the ``conf.py`` file in your docs directory, add or enable ``sphinx.ext.intersphinx`` under ``extensions``: - -.. code-block:: python - :caption: conf.py - - extensions = [ - ... - "sphinx.ext.intersphinx", - ] - -Then, connect to the other project in the ``intersphinx_mapping`` -setting: - -.. code-block:: python - :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) - } - -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```. - -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 inspect the file manually, run: - -.. code-block:: bash - - source .venv/bin/activate - python -m sphinx.ext.intersphinx https://example.com/objects.inv - -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/ - explanation/mode-of-operation How Chisel works : explanation/mode-of-operation/ - std: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 - -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``` diff --git a/docs/how-to/optional-customisation/index.rst b/docs/how-to/optional-customisation/index.rst deleted file mode 100644 index 4b5d2643..00000000 --- a/docs/how-to/optional-customisation/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _optional-customisation: - -Optional customisation ------------------------- - -After the initial setup, you can customize your documentation to fit your project's needs. -This includes adding extensions, modifying the build process, and adding custom templates. - - -.. toctree:: - :maxdepth: 1 - - redirect-pages - Bridge project and docs builds - Enable Google Analytics - Customise PDF output - Use Spread to test commands in documentation - Use custom HTML templates - Add Mermaid diagrams - Add Python docstrings - Add OpenAPI specifications - Add interactive tables - external-referencing-intersphinx - - diff --git a/docs/how-to/optional-customisation/interactive-tables.rst b/docs/how-to/optional-customisation/interactive-tables.rst deleted file mode 100644 index 73969c2f..00000000 --- a/docs/how-to/optional-customisation/interactive-tables.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. meta:: - :description: How to add interactive data tables to your project with sorting and filtering capabilities. - -.. _interactive-tables: - -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. - -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``. - -Then, add ``sphinx_datatables`` to the ``extensions`` list in ``docs/conf.py``. - -Make a table interactive by adding a special CSS class to the directive: - -.. tab-set:: - - .. tab-item:: reST - - .. code-block:: rst - - .. csv-table:: - :class: sphinx-datatable - :file: /howto/assets/animals.csv - :header-rows: 1 - - .. tab-item:: MyST - - .. code-block:: none - - ```{csv-table} - :class: sphinx-datatable - :file: /howto/assets/animals.csv - :header-rows: 1 - ``` - -.. LINKS -.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/ diff --git a/docs/how-to/optional-customisation/mermaid-diagrams.md b/docs/how-to/optional-customisation/mermaid-diagrams.md deleted file mode 100644 index 0dc0f6c0..00000000 --- a/docs/how-to/optional-customisation/mermaid-diagrams.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -myst: - html_meta: - description: How to create and embed diagrams in your documentation using Mermaid. -relatedlinks: https://mermaid.js.org/intro/, https://mermaid.live/ ---- - -(howto-diagram-as-code-mermaid)= - -# 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. - -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. -``` - -## 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: - -```{code-block} text -:emphasize-lines: 6 -canonical-sphinx[full] -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap -sphinxcontrib-mermaid -``` - -Then add "sphinxcontrib.mermaid" in the "extensions" list in `conf.py`: - -```{code-block} python -extensions = [ - [...] - "sphinxcontrib.mermaid", -] -``` - -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. - -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. - -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. -``` - -### Flowchart diagram with default settings - -The left-to-right flowchart below uses the default Mermaid settings. - -```{include} /how-to/assets/mermaid.txt -:start-after: mermaid-diagram-flowchart-start -:end-before: mermaid-diagram-flowchart-end -``` - -### Timeline diagram with pre-defined theme - -The timeline diagram below uses a [pre-defined Mermaid theme]. - -```{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. - -```{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]. - -```{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: - -- [Checkbox](https://canonical-checkbox.readthedocs-hosted.com/stable/explanation/remote/) -- [cloud-init](https://docs.cloud-init.io/en/latest/explanation/boot.html) -- [Charmed MySQL K8s](https://canonical-charmed-mysql-k8s.readthedocs-hosted.com/8.0/explanation/flowcharts/) -- [Ubuntu Pro](https://documentation.ubuntu.com/pro/support-overview/) - -% LINKS - -[Mermaid version]: https://unpkg.com/browse/mermaid/ -[Mermaid configuration values]: https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#config-values -[Mermaid - Diagram syntax]: https://mermaid.js.org/intro/syntax-reference.html -[pre-defined Mermaid theme]: https://mermaid.js.org/syntax/timeline.html#themes -[`classDef` keyword]: https://mermaid.js.org/syntax/stateDiagram.html#styling-with-classdefs -[Official Mermaid documentation]: https://mermaid.js.org/intro/ -[Mermaid Live Editor]: https://mermaid.live/ -[C4 model]: https://c4model.com/ -[Dia]: http://dia-installer.de/ -[PlantUML]: https://plantuml.com/ -[Structurizr]: https://structurizr.com/ - diff --git a/docs/how-to/optional-customisation/openapi-specifications.rst b/docs/how-to/optional-customisation/openapi-specifications.rst deleted file mode 100644 index 0d580228..00000000 --- a/docs/how-to/optional-customisation/openapi-specifications.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. meta:: - :description: How to add an OpenAPI integration to your project. - -.. _how-to-openapi: - -Add OpenAPI integration -======================= - -OpenAPI specifications provide a standardized way to document REST APIs. -This guide demonstrates how to add a minimal OpenAPI integration to your project using `Swagger UI `_, including a basic specification and an opt-in tag toggle based on a build-time environment variable to keep the documentation clean by default. - -Locate the specification ------------------------- - -The stub OpenAPI document can be found under ``docs/how-to/assets/openapi.yaml``. -You can use it as a starting point for your API description: - -.. literalinclude:: ../assets/openapi.yaml - :language: yaml - -Enable the viewer ------------------ - -The OpenAPI interactive viewer is disabled by default. -Exporting the ``OPENAPI`` environment variable when building in your terminal -makes Sphinx copy the specification to the output directory -and add an ``openapi`` tag that we can use in the documentation source:: - - export OPENAPI=1 - -Then rebuild the docs to pick up the specification:: - - make clean html - -.. tip:: - - Unset the variable to go back to the default build:: - - unset OPENAPI - - To enable it for a single command, prefix it like this:: - - OPENAPI=1 make clean html - -Confirm the viewer works ------------------------- - -Serve the documentation locally:: - - make run - -Navigate to ``/how-to/openapi/``. -When the feature flag is enabled, -the page renders the Swagger UI for the shipped specification right here. -The snippet that does this should be included in your documentation source -with the ``.. raw:: html`` directive: - -.. literalinclude:: ../assets/openapi._rst - :language: html - :lines: 2- - -.. only:: openapi - - When added, the snippet above renders the interactive viewer: - - .. include:: ../assets/openapi._rst - -.. only:: not openapi - - .. warning:: - - The interactive viewer is hidden now because ``OPENAPI`` was not set - when this documentation was built. - Export ``OPENAPI=1`` when building the documentation to see it here. - -Building on RTD ---------------- - -To enable the OpenAPI viewer on `Read the Docs `_ tentatively, -define the ``OPENAPI`` environment variable in your project's -`admin settings `_. - -If you're certain that you want the OpenAPI viewer enabled for all builds, -drop all conditional statements from ``conf.py`` and the reST files. -In ``conf.py``, replace the following lines:: - - html_extra_path = [] - - # ... - if os.getenv("OPENAPI", ""): - tags.add("openapi") - html_extra_path.append("how-to/assets/openapi.yaml") - - -With this:: - - html_extra_path = ["how-to/assets/openapi.yaml"] - - -Next, remove any tag-based logic from the reST files:: - - .. only:: openapi - -Troubleshooting ---------------- - -* The ``make html`` command fails with `unknown tag`: - Make sure you exported the environment variable - in the same shell session that runs ``make``. - -* The Swagger UI appears but cannot load the specification: - Make sure that ``openapi.yaml`` exists in the *root* of your build output - or adjust the import paths according to your build structure. - Also, overriding the ``html_extra_path`` setting in ``conf.py`` - may interfere with this configuration - because it is used to copy the specification to the output directory. diff --git a/docs/how-to/optional-customisation/python-docstrings.md b/docs/how-to/optional-customisation/python-docstrings.md deleted file mode 100644 index d548c6c9..00000000 --- a/docs/how-to/optional-customisation/python-docstrings.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -myst: - html_meta: - description: How to import Python docstrings automatically into your documentation using the Sphinx autodoc extension. ---- - -(sphinx-autodoc)= - -# 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. - -## Prerequisites - -To use the Sphinx `autodoc` extension with the Starter Pack, 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 - -## 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: - -```{code-block} python -:caption: {file}`conf.py` - -import sys -from pathlib import Path - -relative_code_path = Path('..', '') -absolute_code_path = relative_code_path.resolve() -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: - -```{code-block} python -:caption: {file}`conf.py` - -extensions = [ - ... - "sphinx.ext.autodoc", -] -``` - -## Usage - -See [Sphinx's `autodoc` instructions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#usage) for details. - -## Known issues and limitations - -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. - -### 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`. - -For documentation that is written in MyST Markdown, wrap the `eval-rst` directive around the `autodoc` calls: - -````{code-block} md - -```{eval-rst} - -.. py:currentmodule:: code. - -.. automodule:: - :members: - -``` -```` - -## Canonical examples - -```{list-table} Canonical autodoc examples -:header-rows: 1 - -* - Product - - {file}`conf.py` - - Raw Doc - - Rendered Doc - -* - Jubilant - - [conf.py](https://github.com/canonical/jubilant/blob/023ce73353352133c43dfb17b4a6cfad0f3e7816/docs/conf.py) - - [jubilant.rst](https://github.com/canonical/jubilant/blob/023ce73353352133c43dfb17b4a6cfad0f3e7816/docs/reference/jubilant.rst) - - [jubilant reference page](https://documentation.ubuntu.com/jubilant/reference/jubilant/) - -* - Ops - - [conf.py](https://github.com/canonical/operator/blob/main/docs/conf.py) - - [ops.rst](https://github.com/canonical/operator/blob/main/docs/reference/ops.rst) - - [*ops* reference page](https://documentation.ubuntu.com/ops/latest/reference/ops/) - -``` diff --git a/docs/how-to/optional-customisation/redirect-pages.md b/docs/how-to/optional-customisation/redirect-pages.md deleted file mode 100644 index 45bfe91e..00000000 --- a/docs/how-to/optional-customisation/redirect-pages.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -myst: - html_meta: - description: How to redirect URLs in your documentation project. You can redirect a URL to a page inside your project, or to a page on another website. -relatedlinks: "[sphinx-rerediraffe](https://github.com/jahn-junior/sphinx-rerediraffe)" ---- - -# 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. - -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. - -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`. - -## 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. - -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 - -# Add redirects, so they can be updated here to land alongside docs being moved -rediraffe_redirects = "redirects.txt" -``` - -## Define a redirect - -Inside your `redirects.txt` file, add your redirects in the following patterns: - -```{code-block} none -:caption: redirects.txt - -# Client-side page redirects -# --------------------------- -# Comments start with a single hash (#) -# Each redirect appears on its own line in the format: -# -# redirect/from/ redirect/to/ -# -# Paths are relative to the root of the `docs` directory -# The "from" path must be a file that *does not* exist -# The "to" path must be a file that *does* exist -# The separator between "from" and "to" paths is a single space (not a tab) - -path/old-name/ path/new-name/ # To rename a file -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. - -## Layer redirects - -Multiple files can be redirected to the same target: - -* A → D -* B → D -* C → D - -Your `redirects.txt` file will look like: - -```{code-block} none -:caption: redirects.txt - -installation tutorial/basic-installation/ -basic-installation tutorial/basic-installation/ -``` - -This is common if files have been renamed more than once, creating layers of redirects. diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst deleted file mode 100644 index a34b5b0c..00000000 --- a/docs/how-to/publish-on-rtd.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. meta:: - :description: How to publish your documentation on Read the Docs. - -.. _publish-on-rtd: - -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. - -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: - -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``". - - 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: - - * ``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. - -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 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. - -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. - -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 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. \ No newline at end of file diff --git a/docs/how-to/run-documentation-checks.rst b/docs/how-to/run-documentation-checks.rst deleted file mode 100644 index 76cdbece..00000000 --- a/docs/how-to/run-documentation-checks.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. 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: - - -- :ref:`accessibility_check` -- :ref:`inclusive_lang_check` -- :ref:`link_check` -- :ref:`markdown_lint_check` -- :ref:`spelling_check` -- :ref:`style_guide_linting` -- :ref:`vale_exemptions` - -.. _accessibility_check: - -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 `_. - -This check is only available locally; it is not part of the Starter Pack's :ref:`github-workflows`. - -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: - -.. code-block:: bash - - make pa11y - -Configure -~~~~~~~~~ - -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: - -.. code-block:: bash - - make woke - -Configure -~~~~~~~~~ - -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: - -.. 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. - -.. _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: - -.. code-block:: bash - - make lint-md - -Configure -~~~~~~~~~ - -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: - -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: - -.. code-block:: bash - - make spelling - -Configure -~~~~~~~~~ - -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: - -.. code-block:: bash - - make vale - -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. - -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`. - -.. _vale_exemptions: -.. _reference-automatic-checks-spelling-vale-ignore: - -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. - -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``: - -.. code-block:: text - - rst_prolog = """ - .. role:: vale-ignore - :class: vale-ignore - """ - -To ignore a word across your documentation, add it to your project's ``.custom_wordlist.txt`` file. - -.. note:: - - 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. - - -A section of text -~~~~~~~~~~~~~~~~~ - -To disable Vale for a section of text, use the following markup: - -.. tab-set:: - - .. tab-item:: Markdown - - .. code-block:: text - - - - This text will be ignored. - - - - .. tab-item:: reST - - .. code-block:: text - - .. vale off - - This text will be ignored. - - .. vale on - - - -Directives -~~~~~~~~~~ - -To disable Vale linting for Directives as a code block or admonitions, apply the `vale-ignore` class to the section: - -.. tab-set:: - - .. tab-item:: Markdown - - .. code-block:: text - - ````{class} vale-ignore - ```{code-block} - - This content will be ignored by Vale. - ``` - ```` - - .. tab-item:: reST - - .. code-block:: text - - .. class:: vale-ignore - .. code-block:: - - 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. - -.. 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 `_. diff --git a/docs/how-to/troubleshooting.rst b/docs/how-to/troubleshooting.rst deleted file mode 100644 index bb91c074..00000000 --- a/docs/how-to/troubleshooting.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. meta:: - :description: How to troubleshoot common issues with the Sphinx Starter Pack and Read the Docs. - -.. _troubleshooting: - -Troubleshooting -=================== - -This page provides guidance to resolve issues with the Starter Pack and Read the Docs -that are difficult to identify or that we don't expect to be solved. - - -Stable version won't build from the latest tag ----------------------------------------------- - -If your project has the ``stable`` version configured to build from tags, such as with -the default `semantic versioning behavior -`_, -your ``stable`` version can become out-of-step and continue building a particular tag, -even when the repository has newer tags. - - -Possible causes -~~~~~~~~~~~~~~~ - -An unwanted tag might have been pushed to the repository and then removed. Once -ReadTheDocs creates a version from a tag, it doesn't later verify that the tag still -exists, so the version will persist and become a zombie. - -If the unwanted tag is a higher iterator than any existing tag, the zombie version will -always take precedence. For example, if tag ``20.2.0`` was pushed by accident and then -replaced with ``2.20.0``, the corresponding version 20.2.0 will persist, and ``stable`` -will continue pointing to it. - - -Diagnosis -~~~~~~~~~ - -There's a roundabout procedure to verify whether your project is affected. Start by -opening your project dashboard on ReadTheDocs. - -On the **Builds** tab, locate the most recent ``stable`` build. For that version, hover -over the status indicator. In the hover box, open the **stable** link. If the resulting -GitHub page is a 404, then your project has a zombie version. - -.. image:: ../how-to/assets/troubleshoot-stable-zombie-version.png - -Resolution -~~~~~~~~~~ - -On your project dashboard, open the **Versions** tab and click **Add version**. - -Find the zombie version, deactivate it, then update it. - -Rebuild ``stable`` by retriggering it on the dashboard or pushing a new tag to the -repository. - - -Issue tracking -~~~~~~~~~~~~~~ - -`readthedocs/readthedocs.org#12450 -`_ 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 553a1b38..00000000 --- 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:`_dev/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 19a91813..00000000 --- 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/_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 # 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 # 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 # 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 # 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 f011f375..00000000 --- a/docs/how-to/update-starter-packs/new-starter-pack.rst +++ /dev/null @@ -1,157 +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 ``/_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 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 ``_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 Starter Pack's. 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 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`` diff --git a/docs/index.rst b/docs/index.rst index e734e208..027f9aa3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,62 +1,43 @@ -Sphinx Starter Pack documentation -================================= - -The documentation Starter Pack helps you to quickly 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. +Project +======= In this documentation --------------------- -.. grid:: 1 1 2 2 - - .. grid-item-card:: Get started - :link: /set-up-a-new-project - :link-type: doc - - Set up the Sphinx Starter Pack in your project for the first time. - .. grid-item-card:: How-to guides - :link: /how-to/index - :link-type: doc +How this documentation is organized +----------------------------------- - **Step-by-step guides** - learn key operations and customisation. -.. grid:: 1 1 2 2 - - .. grid-item-card:: Reference - :link: /reference/index - :link-type: doc +Project and community +--------------------- - **Technical information** - review the automatic checks and Sphinx capabilities. - .. grid-item-card:: Explanation - :link: /explanation/index - :link-type: doc +Get involved +~~~~~~~~~~~~ - **Concepts** - understand the design and architecture of the Starter Pack. +Releases and support +~~~~~~~~~~~~~~~~~~~~ -Project and community ----------------------- -The Canonical Sphinx Starter Pack is an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback. +Governance and policies +~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :hidden: - :maxdepth: 2 + :maxdepth: 1 - Set up a new project - How-to guides - Reference - Explanation + tutorials/index + how-to/index + reference/index + explanation/index .. toctree:: :hidden: + :maxdepth: 1 - Release notes - Contribute + release-notes/index + contribute/index diff --git a/docs/redirects.txt b/docs/redirects.txt index 3ba6791c..cf8ae225 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -6,52 +6,3 @@ # The old path must be a file that doesn"t exist in the source. The current path must be # a file that does exist in the source. - -"tutorial/" "set-up-a-new-project" -"tutorial/set-up-automated-testing/" "how-to/optional-customisation/add-documentation-testing" -"tutorial/set-up/" "set-up-a-new-project" - -"how-to/customise/" "how-to/configure-your-project" -"how-to/rtd/" "how-to/publish-on-rtd" -"how-to/update/" "how-to" -"how-to/prereqs/" "how-to" -"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/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" -"how-to/customise-pdf/" "how-to/optional-customisation/customise-pdf" -"how-to/diagrams-as-code-mermaid/" "how-to/optional-customisation/mermaid-diagrams" -"how-to/import-docstrings-with-autodoc/" "how-to/optional-customisation/" -"how-to/openapi/" "how-to/optional-customisation/openapi-specifications" -"how-to/troubleshoot-issues/" "how-to/troubleshooting" -"how-to/set-up-sitemaps/" "explanation/sitemaps" -"how-to/add-documentation-testing/" "how-to/optional-customisation/add-documentation-testing" -"how-to/test-ulwazi-theme/" "contribute/test-ulwazi-theme" -"how-to/enable-google-analytics/" "how-to/optional-customisation/enable-google-analytics" - -"reference/removed-url-check/" "reference/github-workflows" -"reference/automatic_checks_removed-url-check" "reference/github-workflows" -"reference/myst-syntax-reference/" "reference/myst-syntax" -"reference/style-guide-myst/" "reference/myst-syntax" -"reference/doc-cheat-sheet-myst/" "reference/myst-syntax" -"reference/rst-syntax-reference/" "reference/rst-syntax" -"reference/style-guide/" "reference/rst-syntax" -"reference/doc-cheat-sheet/" "reference/rst-syntax" - -"reference/doc-cheat-sheet-myst" "reference/myst-syntax-reference" -"reference/style-guide-myst" "reference/myst-syntax-reference" -"reference/doc-cheat-sheet" "reference/rst-syntax-reference" -"reference/style-guide" "reference/rst-syntax-reference" - - -"reference/automatic_checks" "how-to/run-documentation-checks" -"reference/automatic_checks_accessibility" "how-to/run-documentation-checks" -"reference/automatic_checks_inclusivelanguage" "how-to/run-documentation-checks" -"reference/automatic_checks_links" "how-to/run-documentation-checks" -"reference/automatic_checks_linting" "how-to/run-documentation-checks" -"reference/automatic_checks_spelling" "how-to/run-documentation-checks" -"reference/automatic_checks_styleguide" "how-to/run-documentation-checks" diff --git a/docs/reference/default-extensions.rst b/docs/reference/default-extensions.rst deleted file mode 100644 index e19586fc..00000000 --- a/docs/reference/default-extensions.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. meta:: - :description: A list of extensions included in the Starter Pack by default. - -.. _reference-default-sphinx-extensions: - -Default Sphinx extensions -========================= - -These extensions are enabled in the Starter Pack by default. - -``canonical_sphinx`` - Contains the default Canonical branded theme. - -``notfound.extension`` - Allows creating custom 404 pages. - Needed by ``canonical_sphinx``. - -``sphinx_design`` - Provides UI components like responsive grids, cards, and badges. - - Needed by ``canonical_sphinx``. - -``sphinx_reredirects`` - 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. - - Needed by ``canonical_sphinx``. - -``sphinx_tabs.tabs`` - Provides tabs. - - Needed by ``canonical_sphinx``. - -``sphinxcontrib.jquery`` - Ensures jQuery is loaded to maintain compatibility with older extensions and themes. - - Needed by ``canonical_sphinx``. - -``sphinxext.opengraph`` - Generates OpenGraph metadata to create rich preview cards when links are shared on social media. - - Needed by ``canonical_sphinx``. - -``sphinxext-rediraffe`` - Handles URL redirects for moved or deleted pages. Redirects can be defined as a - dictionary in the ``conf.py`` file or in a separate file. - -``sphinx.ext.intersphinx`` - Generates automatic links to the documentation objects of other Sphinx projects. - -``sphinx_config_options`` - Provides customized directives to easily document system or project configuration options. - -``sphinx_contributor_listing`` - Automatically generates a list of contributors to the project repository. - -``sphinx_filtered_toctree`` - Filters Table of Contents (``toctree``) entries based on specific tags or conditions. - -``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. - -``sphinx_roles`` - Provides custom inline text roles for standardized formatting or linking across the project. - -``sphinx_sitemap`` - Automatically generates a standard sitemap.xml file to improve indexing for search engine optimization (SEO). - -``sphinx_terminal`` - Renders styled terminal sessions and command-line output within the documentation. - -``sphinx_ubuntu_images`` - Generates lists of official Ubuntu disk images for specific release ranges and architectures. - -``sphinx_youtube_links`` - Provides a directive to embed YouTube videos into a page. - -``sphinxcontrib.cairosvgconverter`` - Converts SVG images into PDF. - diff --git a/docs/reference/github-workflows.rst b/docs/reference/github-workflows.rst deleted file mode 100644 index 10ebea6f..00000000 --- a/docs/reference/github-workflows.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. 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 ``documentation-checks.yaml`` workflow covers these three checks and can be added to a new or existing workflow's jobs with: - -.. code:: yaml - - jobs: - [...] - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - 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``: - -.. code:: yaml - - jobs: - spell-check: - uses: canonical/documentation-workflows/.github/workflows/spelling-check.yaml@main - with: - working-directory: "docs" - inclusive-language-check: - uses: canonical/documentation-workflows/.github/workflows/inclusive-language-check.yaml@main - with: - working-directory: "docs" - link-check: - uses: canonical/documentation-workflows/.github/workflows/link-check.yaml@main - with: - working-directory: "docs" - - -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: - -.. list-table:: - :header-rows: 1 - - * - Input - - Description - - Default - * - ``working-directory`` - - The root of the documentation project. This input is required. - - None - * - ``python-version`` - - The Python interpreter to use for the workflow's jobs. - - The default Python version use. Example: ``'3.10'`` - * - ``fetch-depth`` - - The number of commits to fetch from your repository. - - The full history is fetched. - * - ``runs-on`` - - The host system for the workflow's runners. - - The current Ubuntu LTS. Example: ``'["ubuntu-24.04"]'`` - * - ``makefile`` - - The Makefile that checks are invoked from. - - ``'Makefile'`` - * - ``install-target`` - - The make target for installing required tools. - - ``'install'`` - * - ``spelling-target`` - - The make target to run for the spelling check. - - ``'spelling'`` - * - ``woke-target`` - - The make target to run for the inclusive language check. - - ``'woke'`` - * - ``linkcheck-target`` - - The make target to run for the link check. - - ``'linkcheck'`` - - -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. - -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. - diff --git a/docs/reference/include.txt b/docs/reference/include.txt deleted file mode 100644 index e59fdd84..00000000 --- a/docs/reference/include.txt +++ /dev/null @@ -1,3 +0,0 @@ -[include_start] -I feel included! -[include_end] diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 9cc1f3a5..2a21ad05 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,21 +1,4 @@ +.. _reference: + Reference ========= - -Syntax guides, list of enabled sphinx extensions, and reference information -for the Starter Pack's GitHub workflows. - -Also see the following information: - -- `Canonical's Sphinx Starter Pack `__ - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - github-workflows - default-extensions - rst-syntax - myst-syntax - diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md deleted file mode 100644 index f352227d..00000000 --- a/docs/reference/myst-syntax.md +++ /dev/null @@ -1,987 +0,0 @@ ---- -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: Reference for the MyST syntax conventions used by Canonical. - substitutions: - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" ---- - -(myst-syntax)= - -# MyST syntax - -The Starter Pack 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). -``` - -For general style conventions, see the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en). - -## Headings - -```{list-table} - :header-rows: 1 - -* - Input - - Description -* - `# Title` - - Page title and H1 heading -* - `## Heading` - - H2 heading -* - `### Heading` - - H3 heading -* - `#### Heading` - - H4 heading -* - ... - - Further headings -``` - -Adhere to the following conventions: - -- Do not use consecutive headings without intervening text. -- Do not skip levels (for example, do not follow an H2 heading with an H4 heading). -- Use sentence style for headings (capitalise only the first word). - -## Inline formatting - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `` {guilabel}`UI element` `` - - {guilabel}`UI element` -* - `` `code` `` - - `code` -* - `` {file}`file path` `` - - {file}`file path` -* - `` {command}`command` `` - - {command}`command` -* - `` {kbd}`Key` `` - - {kbd}`Key` -* - `*Italic*` - - *Italic* -* - `**Bold**` - - **Bold** - -``` - -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. - -## Code blocks - -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. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ``` - # Demonstrate a code block - code: - - example: true - ``` - - ```` - - - ``` - # Demonstrate a code block - code: - - example: true - ``` -* - ```` - - ```yaml - # Demonstrate a code block - code: - - example: true - ``` - - ```` - - - ```yaml - # Demonstrate a code block - code: - - example: true - - ``` - -````` - -To include back ticks in a code block, increase the number of surrounding back ticks: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - - ````` - - ```` - ``` - ```` - - ````` - - - - ```` - - ``` - - ```` - -````` - -### Terminal output - -A terminal view can be useful to show the output of a specific command, where it is -important to see the difference between input and output. In addition, including a -terminal view can help break up a long text and make it easier to consume, which is -especially useful when documenting command-line-only products. - -To show a terminal view, use the following directive: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - ``` - ```` - - ```{terminal} - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - ``` -````` - -By default, everything before the first blank line in the directive's content is -rendered as input, while any content that follows is rendered as output. The terminal -directive can only display one input command, but that command can span multiple lines, -as in the previous example. - -To render only the output of a command, include the `:output-only:` flag as a directive -option: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - :output-only: - - This is rendered as output. - ``` - ```` - - ```{terminal} - :output-only: - - This is rendered as output. - ``` -````` - -To customize the prompt (`user@host:~$` by default), specify any of the following options: - -* `:user:` -* `:host:` -* `:dir:` - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - :user: author - :host: canonical - :dir: ~/path - - input - - output - ``` - ```` - - ```{terminal} - :user: author - :host: canonical - :dir: ~/path - - input - - output - ``` -````` - -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. - -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. - -### 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. - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `[Canonical website](https://canonical.com)` - - [Canonical website](https://canonical.com) -* - `https://canonical.com` - - [{spellexception}`https://canonical.com`](https://canonical.com) -* - ``[`https://canonical.com`](https://canonical.com)`` - - [`https://canonical.com`](https://canonical.com) -``` - -To display a URL as text and prevent it from being linked, add a ``: - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `https://canonical.com` - - {spellexception}`https://canonical.com` - -``` - -#### Related links - -You can add links to related websites or Discourse topics to the sidebar - -To add a link to a related website, add the following field at the top of the page: - - 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 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): - - discourse: 12345 - -#### YouTube links - -To add a link to a YouTube video, use the following directive: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - ``` - - ```` - - - ```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - ``` - -````` - -The video title is extracted automatically and displayed when hovering over the link. -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. - -(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. - -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)= - -```{list-table} - :header-rows: 1 - :widths: 7 3 3 - -* - Input - - Output - - Description -* - `(target_ID)=` - - - - Adds the target ``target_ID``. -* - `` {ref}`a_section_target_myst` `` - - {ref}`a_section_target_myst` - - References a target that has a title. -* - `` {ref}`link text ` `` - - {ref}`link text ` - - 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. -* - ``[`xyz`](a_random_target_myst)`` - - [`xyz`](a_random_target_myst) - - Use Markdown syntax if you need markup on the link text. -``` - -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. - -#### 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. - -```{list-table} - :header-rows: 1 - -* - Input - - Output - - Status -* - `` {doc}`index` `` - - {doc}`index` - - Preferred. -* - `[](index)` - - [](index) - - Do not use. -* - `[Index page](index)` - - [Index page](index) - - Preferred when overriding the link text. -* - `` {doc}`Index page ` `` - - {doc}`Index page ` - - Alternative when overriding the link text. -``` - -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. - -## 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: - -```` -```{toctree} -:hidden: - -sub-page1 -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: - -``` ---- -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. - -To exclude pages from the build, add them to the `custom_excludes` variable in the {file}`conf.py` file. -``` - -## Lists - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - - Item 1 - - Item 2 - - Item 3 - ``` - - - Item 1 - - Item 2 - - Item 3 -* - ``` - 1. Step 1 - 1. Step 2 - 1. Step 3 - ``` - - 1. Step 1 - 1. Step 2 - 1. Step 3 -* - ``` - 1. Step 1 - - Item 1 - * Sub-item - - Item 2 - 1. Step 2 - 1. Sub-step 1 - 1. Sub-step 2 - ``` - - 1. Step 1 - - Item 1 - * Sub-item - - Item 2 - 1. Step 2 - 1. Sub-step 1 - 1. Sub-step 2 -```` - -Adhere to the following conventions: - -- In numbered lists, use `1.` for all items to generate the step numbers automatically. - You can also use a higher number for the first item to start with that number. -- Use `-` for unordered lists. When using nested lists, you can use `*` for the nested level. - -### Definition lists - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - Term 1 - : Definition - - Term 2 - : Definition - ``` - - Term 1 - : Definition - - Term 2 - : Definition -```` - -(myst_style_guide_tables)= - -## 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. - -Both markups result in the following output: - -```{list-table} - :header-rows: 1 - -* - Header 1 - - Header 2 -* - Cell 1 - - Second paragraph cell 1 - - Cell 2 -* - Cell 3 - - Cell 4 -``` - -### Markdown tables - -``` -| Header 1 | Header 2 | -|------------------------------------|----------| -| Cell 1

    2nd paragraph cell 1 | Cell 2 | -| Cell 3 | Cell 4 | -``` - -### List tables - -See [list tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) for reference. - -```` -```{list-table} - :header-rows: 1 - -* - Header 1 - - Header 2 -* - Cell 1 - - 2nd paragraph cell 1 - - Cell 2 -* - Cell 3 - - Cell 4 -``` -```` - -### Data tables - -If you have a small amount of CSV data, you can include the data in the doc source. - -For example: - -```` -```{csv-table} -:header-rows: 1 - -"Animal", "Number of legs", "Size" - -"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. - -For example: - -```` -```{csv-table} -:file: /reuse/animals.csv -:header-rows: 1 -``` -```` - -Both markups result in the following output: - -```{csv-table} -:header-rows: 1 - -"Animal", "Number of legs", "Size" - -"Worm", 0, "Small" -"Penguin", 2, "Medium" -"Horse", 4, "Large" -"Ant", 6, "Small" -"Octopus", 8, "Medium" -``` - -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`. - -## Notes - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - ```{note} - A note. - ``` - ```` - - ```{note} - A note. - ``` -* - ```` - ```{tip} - A tip. - ``` - ```` - - ```{tip} - A tip. - ``` -* - ```` - ```{important} - Important information - ``` - ```` - - ```{important} - Important information. - ``` -* - ```` - ```{caution} - This might damage your hardware! - ``` - ```` - - ```{caution} - This might damage your hardware! - ``` -````` - -Adhere to the following conventions: - -- Use notes sparingly. -- Only use the following note types: `note`, `tip`, `important`, `caution` -- Only use a caution if there is a clear hazard of hardware damage or data loss. - -## Images - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - ![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) - ``` - - ![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) -* - ```` - ```{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 - ``` -```` - -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. - -## Reuse - -A big advantage of MyST in comparison to plain Markdown is that it allows to reuse content. - -### 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). - -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`. 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`" - - import os - import yaml - - ... - - 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)" - } - ``` - - ```{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: - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `{{version_number}}` - - {{version_number}} -* - `{{formatted_text}}` - - {{formatted_text}} -* - `{{site_link}}` - - {{site_link}} -* - `{{advanced_reuse_key}}` - - {{advanced_reuse_key}} -``` - -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`). - -### 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 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. - -By combining file inclusion and substitutions, you can even replace parts of the included text. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - % Include parts of the content from - % file rst-syntax.rst - ```{include} rst-syntax.rst - :start-after: "Adhere to the following conventions:" - :end-before: " Use the ones specified above." - ``` - - ```` - - - - % Include parts of the content from file [rst-syntax.rst](rst-syntax.rst) - ```{include} rst-syntax.rst - :start-after: "Adhere to the following conventions:" - :end-before: " Use the ones specified above." - ``` - -````` - -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. - -## 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. - -``````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````` - - ````{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](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 - -* - Input - - Output -* - ````` - - ````{tabs} - - ```{group-tab} Tab 1 - - Content Tab 1 - ``` - - ```{group-tab} Tab 2 - - Content Tab 2 - ``` - - ```` - - ````` - - - ````{tabs} - - ```{group-tab} Tab 1 - - Content Tab 1 - ``` - - ```{group-tab} Tab 2 - - Content Tab 2 - ``` - ```` -`````` - -## Collapsible sections - -There is no support for details sections in MyST, but you can insert HTML to create them. - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` -
    - Details - - Content -
    - ``` - - -
    - Details - - Content -
    - -```` - -## 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. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ```{glossary} - - MyST example term - Definition of the example term. - ``` - - ```` - - - ```{glossary} - - MyST example term - Definition of the example term. - ``` - -* - ``{term}`MyST example term` `` - - {term}`MyST example term` -````` - -## More useful markup - -`````{list-table} - :header-rows: 1 - -* - Input - - Output - - Description -* - ```` - - ```{versionadded} X.Y - ``` - - ```` - - ```{versionadded} X.Y - ``` - - Can be used to distinguish between different versions. -* - ``` - --- - ``` - - A horizontal line - - Can be used to visually divide sections on a page. -* - ``` - - ``` - - - - 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/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst deleted file mode 100644 index 9353991e..00000000 --- a/docs/reference/rst-syntax.rst +++ /dev/null @@ -1,988 +0,0 @@ -.. meta:: - :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) - -.. _rst-syntax: - -reStructuredText syntax -======================= - -The documentation files use `reStructuredText `_ (reST) syntax. - -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 `_. - -Headings --------- - -.. list-table:: - :header-rows: 1 - - * - Input - - Description - * - .. code:: - - Title - ===== - - Page title and H1 heading - * - .. code:: - - Heading - ------- - - H2 heading - * - .. code:: - - Heading - ~~~~~~~ - - H3 heading - * - .. code:: - - Heading - ^^^^^^^ - - H4 heading - * - .. code:: - - Heading - ....... - - H5 heading - -Underlines must be at least as long as the title or heading. - -Adhere to the following conventions: - -- Do not use consecutive headings without intervening text. -- Be consistent with the characters you use for each level. - Use the ones specified above. -- Use sentence style for headings (capitalise only the first word). - -Inline formatting ------------------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - ``:guilabel:`UI element``` - - :guilabel:`UI element` - * - ````code```` - - ``code`` - * - ``:file:`file path``` - - :file:`file path` - * - ``:command:`command``` - - :command:`command` - * - ``:kbd:`Key``` - - :kbd:`Key` - * - ``*Italic*`` - - *Italic* - * - ``**Bold**`` - - **Bold** - -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. - -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. - -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 `_. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - Demonstrate a code block:: - - code: - - example: true - - Demonstrate a code block:: - - code: - - example: true - * - .. code:: - - .. code:: - - # Demonstrate a code block - code: - - example: true - - .. code:: - - # Demonstrate a code block - code: - - example: true - * - .. code:: - - .. code:: yaml - - # Demonstrate a code block - code: - - example: true - - .. code:: yaml - - # Demonstrate a code block - code: - - example: true - -Terminal output -~~~~~~~~~~~~~~~ - -A terminal view can be useful to show the output of a specific command, where it is -important to see the difference between input and output. In addition, including a -terminal view can help break up a long text and make it easier to consume, which is -especially useful when documenting command-line-only products. - -To include a terminal view, use the following directive: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - - .. terminal:: - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - -By default, everything before the first blank line in the directive's content is -rendered as input, while any content that follows is rendered as output. The terminal -directive can only display one input command, but that command can span multiple lines, -as in the previous example. - -To render only the output of a command, include the ``:output-only:`` flag in the -directive's options: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - :output-only: - - This is rendered as output. - - - .. terminal:: - :output-only: - - This is rendered as output. - -To customize the prompt (``user@host:~$`` by default), specify any of the following options: - -* ``:user:`` -* ``:host:`` -* ``:dir:`` - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - :user: author - :host: canonical - :dir: ~/path - - input - - output - - .. terminal:: - :user: author - :host: canonical - :dir: ~/path - - input - - output - -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. - -For more details, refer to the `sphinx-terminal README `_. - -Links ------ - -Link markup depends on whether you need an external URL -or a page in the same documentation set. - - -External links -~~~~~~~~~~~~~~ - -For external links, use one of the following methods. - -Link inline: - Define occasional links directly within the surrounding text. - To make the link text show up in code-style (which excludes it from the spelling check), use the ``:literalref:`` role. - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ```Canonical website `_`` - - `Canonical website `_ - - * - ``:literalref:`ubuntu.com``` - - :literalref:`ubuntu.com` - * - ``:literalref:`xyzcommand ``` - - :literalref:`xyzcommand ` - - You can also use a URL as is (``https://example.com``), - but that might cause spellchecker errors. - - .. tip:: - - To prevent a URL from appearing as a link, - add an escaped space character (``https:\ //``). - The space won't be rendered: - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ``https:\ //canonical.com/`` - - :spellexception:`https://canonical.com/` - - -Define the links at the bottom of the page: - To keep the text readable, group the link definitions below. - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - - * - ```Canonical website`_`` - - `Canonical website`_ - - Using the below defined link - - * - .. code:: - - .. LINKS - .. _Canonical website: https://canonical.com/ - - *n/a* - - Defining links at the bottom - - -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 rst_epilog `_). - - .. code-block:: python - :caption: :spellexception:`conf.py` - - custom_rst_epilog = """ - .. include:: reuse/links.txt - """ - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ```Canonical website`_`` - - `Canonical website`_ - -Related links -^^^^^^^^^^^^^ - -You can add links to related websites or Discourse topics to the sidebar. - -To add a link to a related website, add the following field at the top of the page:: - - :relatedlinks: https://github.com/canonical/lxd-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 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):: - - :discourse: 12345 - -Manual-page links -^^^^^^^^^^^^^^^^^ - -When mentioning command line utilities, you may wish to link to the -corresponding manual page for the command. Ensure that the ``manpages_url`` -setting in your :file:`conf.py` is set appropriately and use the ``:manpage:`` -inline role within your text to create a link. - -For example, to link to man pages from the 24.04 LTS (Noble Numbat) release, -include the following in your :file:`conf.py`: - -.. code-block:: python - - manpages_url = "https://manpages.ubuntu.com/manpages/noble/en/man{section}/{page}.{section}.html" - -Then within your documentation, use the following reST: - -.. code-block:: rst - - You can use the :manpage:`dd(1)` utility to write the disk image to your - SD card. If the image is compressed, use :manpage:`aunpack(1)` to extract - it first. - - -YouTube links -^^^^^^^^^^^^^ - -To add a link to a YouTube video, use the following directive: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - - - .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - -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 -^^^^^^^^^^^^^^^^^^^^^ - -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. - -.. _a_random_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. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - * - ``.. _target_ID:`` - - - - Adds the target ``target_ID``. - - .. note:: - When defining the target, you must prefix it with an underscore. Do not use the starting underscore when referencing the target. - * - ``:ref:`a_section_target``` - - :ref:`a_section_target` - - References a target that has a title. - * - ``:ref:`Provided link text ``` - - :ref:`Provided link text ` - - References a target and specifies a title. - * - ``:external+project_key:ref:`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. - -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 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 -^^^^^^^^^^^^^^^^^^ - -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. - -.. list-table:: - :header-rows: 1 - :widths: 8 2 - - * - Input - - Output - * - ``:doc:`index``` - - :doc:`index` - * - ``:doc:`Provided link text ``` - - :doc:`Provided link text ` - * - ``:external+project_key:doc:`howto/index``` - - Default link text (from document title) - * - ``:external+project_key:doc:`Provided link text ``` - - Provided link text - -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``. - -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:: - - .. toctree:: - :hidden: - - 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. - -.. 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. - -Lists ------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - - 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 - - .. code:: - - 1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 - #. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - .. tab-item:: Output - - - - 1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 - #. 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. - -Definition lists -~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - 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. - -Both markups result in the following output: - -.. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Grid tables -~~~~~~~~~~~ - -See `grid tables `_ for reference. - -.. code:: - - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | 2nd paragraph cell 1 | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ - -List tables -~~~~~~~~~~~ - -See `list tables `_ for reference. - -.. code:: - - .. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - 2nd paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Data tables -~~~~~~~~~~~ - -If you have a small amount of CSV data, you can include the data in the doc source. - -For example: - -.. code-block:: rst - - .. csv-table:: - :header: "Animal", "Number of legs", "Size" - - "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. - -For example: - -.. code-block:: rst - - .. csv-table:: - :file: /assets/animals.csv - :header-rows: 1 - -Both markups result in the following output: - -.. csv-table:: - :header: "Animal", "Number of legs", "Size" - - "Worm", 0, "Small" - "Penguin", 2, "Medium" - "Horse", 4, "Large" - "Ant", 6, "Small" - "Octopus", 8, "Medium" - -Customize the column widths, character encoding, and so on, as described in the -`csv-table reference `_. - -The Starter Pack can also render interactive tables. See: :ref:`interactive-tables`. - -Notes ------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. note:: - A note. - - .. note:: - A note. - * - .. code:: - - .. warning:: - This might damage your hardware! - - .. warning:: - This might damage your hardware! - -Adhere to the following conventions: - -- Use notes sparingly. -- 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 - - * - 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 caption - - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - -Adhere to the following conventions: - -- For local pictures, start the path with :file:`/` (for example, :file:`/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. - -Reuse ------ - -A big advantage of reST in comparison to plain Markdown is that it allows to reuse content. - -Substitution -~~~~~~~~~~~~ - -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 rst_epilog `_): - -.. code-block:: python - :caption: :spellexception:`conf.py` - - rst_epilog = """ - .. include:: reuse/substitutions.txt - """ - - -.. code-block:: rest - :caption: :spellexception:`reuse/substitutions.txt` - - .. |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 - - -**Locally**, putting the same directives in any reST file: - -.. code-block:: rest - :caption: :spellexception:`index.rst` - - .. |version_number| replace:: 0.1.0 - - .. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - - .. And so on - - -.. note:: - - Mind that substitutions can't be redefined; - for instance, accidentally including a definition twice causes an error: - - .. code-block:: none - - ERROR: Duplicate substitution definition name: "rest_text". - - -The definitions from the above examples are rendered as follows: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ``|version_number|`` - - |version_number| - - * - ``|rest_text|`` - - |rest_text| - - * - ``|site_link|_`` - - |site_link|_ - - -.. tip:: - - 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 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. - -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 - - * - Input - - Output - * - .. code:: - - .. include:: index.rst - :start-after: Also see the following information: - :end-before: Contents - - .. include:: index.rst - :start-after: Also see the following information: - :end-before: Contents - -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. - -Tabs ----- - -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. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - - .. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: 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. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. 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` - -.. _section_more_useful_markup: - -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:: - - ---- - - 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.4.rst b/docs/release-notes/1.4.rst deleted file mode 100644 index d7f0f130..00000000 --- a/docs/release-notes/1.4.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.4.0. - - -.. _release-1.4: - -Canonical's Sphinx Starter Pack 1.4 -=================================== - -28 January 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.4.0. The `full commit log -`__ is -available on GitHub. - - -What's new in 1.4.0 -------------------- - - -Bridging the build -~~~~~~~~~~~~~~~~~~ - -The docs build and its Make targets are hosted in the ``docs`` directory. If the docs -are in a larger project with its own build system, it can be difficult to maintain and -run the two separate builds. - -We've taken some initial steps to make the docs build easier to integrate into larger -projects. With 1.4.0, the docs ``Makefile`` is now properly callable by a parent build -system, because the main build can ensure the ``VENVDIR``, ``BUILDDIR``, and ``VALEDIR`` -variables are set to the right locations in the project. - -The new guide :ref:`bridge-project-and-docs-builds` covers in detail how to integrate the -docs build in a parent Python project. - - -Build explanation -~~~~~~~~~~~~~~~~~ - -We've released an :ref:`explanation of the starter pack build ` to -share with you some of its design and inner workings. - - -Removed in 1.4.0 ----------------- - - -Metrics check -~~~~~~~~~~~~~ - -The metrics check was a set of scripts called with ``make allmetrics`` that collected -measures and statistics about source documents and rendered HTML files. - -We've removed this check because it was underused and underdeveloped. There have been no -reported usages of it from any active projects at Canonical. - - -Fixed bugs and issues ---------------------- - -1.4.0 -~~~~~ - -- `#496 `__ myst-parser - causes Python dependency check to time out -- `#509 `__ Markdown - linter falsely flags contents of ``.sphinx`` dir - - -1.4.1 -~~~~~ - -- `#444 `__ Patch the - ``version`` file so the upgrade script works - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this -release: - -:literalref:`medubelko `, -:literalref:`minaelee `, and -:literalref:`tang-mm ` diff --git a/docs/release-notes/1.5.rst b/docs/release-notes/1.5.rst deleted file mode 100644 index 45bf075d..00000000 --- a/docs/release-notes/1.5.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.5. - - -.. _release-1.5: - -Canonical's Sphinx Starter Pack 1.5 -=================================== - -26 February 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.5. The `full commit log -`__ 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 ` - - -What's new in 1.5 ------------------ - - -New versioning -~~~~~~~~~~~~~~ - -We've revised our approach to versions. Because the starter pack is an evergreen -repository and not packaged software, it requires a different version process and -scheme. - -Starting with 1.5, the starter pack only provides major and minor version numbers. Patch -numbers now correspond to the Git commits in the repository's ``main`` branch between -tagged releases. - -.. image:: assets/release-commit-history.svg - :alt: A mock linear Git commit history of the main branch, with nodes for tagged minor versions and intermediate untagged commits. - :width: 75% - -Going forward, we'll continue to tag major and minor releases, and distribute hotfixes -to the tip of the repository's history. If untagged patch versions are too risky, or -your software policy requires that you lock to a specific version, we recommend you pin -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`. - - -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. - - -Quiet link check -~~~~~~~~~~~~~~~~ - -The link check by default was too verbose, logging every checked link. - -The check now only logs on errors. - - -Environment variable updates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For docs embedded into larger projects, the Make commands might be called in the -project's main build system. Because docs builds used common names like ``BUILDDIR``, it -was possible that they could conflict with variables set by the parent build system -meant for other software. - -We made all the docs variables conditional, so you can set them ahead of time in the -parent build system. - -To mediate the risk of conflicts, we overhauled the variable names, adding a prefix and -splitting along common word boundaries. - -.. list-table:: - :header-rows: 1 - :widths: 1 3 - - * - Old variable name - - New variable name - * - ``VENVDIR`` - - ``DOCS_VENVDIR`` - * - ``VENV`` - - ``DOCS_VENV`` - * - ``SOURCEDIR`` - - ``DOCS_SOURCEDIR`` - * - ``REQPDFPACKAGES`` - - ``DOCS_PDFPACKAGES`` - * - ``VOCAB_CANONICAL`` - - ``DOCS_VOCAB`` - * - ``SPHINXDIR`` - - ``SPHINX_DIR`` - * - ``SPHINXBUILD`` - - ``SPHINX_BUILD`` - * - ``VALEDIR`` - - ``VALE_DIR`` - * - ``VALECONFIG`` - - ``VALE_CONFIG`` - * - ``TARGET`` - - ``CHECK_PATH`` - - -Dependency changes in 1.5 -------------------------- - -.. list-table:: - :header-rows: 1 - :widths: 2 1 1 - - * - Package - - From - - To - * - canonical-sphinx - - >=0.5.1 - - ~=0.6 - * - sphinx-related-links - - >=0.1.1 - - >=0.1.2 - - -Removed in 1.5 --------------- - - -``wokeignore`` directive -~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``wokeignore`` directive is removed because it was redundant. Use the -:literalref:`vale-ignore ` role -instead. - - -Contribution guide template -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We removed a contribution guide template that was placed in the documentation in error. - - -Fixed in 1.5 ------------- - -- `#472 `__ invalid - characters in Makefile cause infinite loop -- `#477 `__ Version slug - is duplicated in sitemaps -- `#501 `__ - Example-product docs are used in links but no longer available -- `#514 `__ Workflows - can be called by other projects - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this release: - -:literalref:`a-velasco `, -:literalref:`akcano `, -:literalref:`jahn-junior `, -:literalref:`medubelko `, -:literalref:`minaelee `, -:literalref:`nhennigan `, and -:literalref:`odadacharles ` diff --git a/docs/release-notes/1.6.rst b/docs/release-notes/1.6.rst deleted file mode 100644 index 52feaad8..00000000 --- a/docs/release-notes/1.6.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.6. - - -.. _release-1.6: - -Canonical's Sphinx Starter Pack 1.6 -=================================== - -24 March 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.6. The `full commit log -`__ 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 ` - - -What's new in 1.6 ------------------ - - -New extension for redirects -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your project has a lot of redirects, they can begin to clutter your build -configuration file. To remedy this, we changed the default extension for redirects to -sphinx-rerediraffe, a fork of sphinxext-rediraffe that supports external redirects and -cleans up destination URLs. - -In your docs, you can now list redirects in a ``redirects.txt`` file and configure your -project to use them with: - -.. code-block:: diff - :caption: conf.py - :class: no-copybutton - - - redirects = { - - "source-path": "destination-path" - - } - + rediraffe_redirects = "redirects.txt" - + rediraffe_dir_only = True - -If your project uses relative redirects, these should be rewritten relative to the -root of the docs directory. - -For example, if you were previously redirecting ``/how-to/set-up/project/`` to -``../set-up-project/``, the redirect should now read: - -.. code-block:: text - :caption: redirects.txt - :class: no-copybutton - - "/how-to/set-up/project/" "/how-to/set-up-project/" - - -Remote cookie banner files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Following the recent changes to the cookie banner, we evaluated how its files are -distributed and maintained. In version 1.6, these files are hosted centrally so you -don't need to duplicate them to enable Google Analytics for your project. - -If you've already enabled Google Analytics in your project, you should make it a -priority to use the centrally-hosted files, as they contain important legal changes. For -guidance, refer to :ref:`how-to-enable-google-analytics`. - - -Virtual environment path -~~~~~~~~~~~~~~~~~~~~~~~~ - -To make the Python virtual environment more discoverable, we moved it from -``docs/.sphinx/venv`` to ``docs/.venv``. This also preserves the ``.sphinx/`` -directory's scope, which is to house static utility files. - -Once you've replaced all occurrences of the old path, remove the old virtual -environment. - - -Ulwazi testing guide -~~~~~~~~~~~~~~~~~~~~ - -Our new Sphinx theme based on the Vanilla framework, Ulwazi, is now available for -testing. To try it out, follow the new guide, :ref:`how-to-test-ulwazi-theme`. - - -Starter Pack explanation -~~~~~~~~~~~~~~~~~~~~~~~~ - -We published :ref:`explanation-structure` to explain the functionality of and -relationships between the core elements of the Starter Pack. - - -Deprecated features -------------------- - -The following features are deprecated and will be removed in an upcoming version of -the Starter Pack. - - -sphinx-reredirects -~~~~~~~~~~~~~~~~~~ - -The sphinx-reredirects extension is deprecated in 1.6. Redirects, both internal and -external, should now be handled with sphinx-rerediraffe. - - -Fixed for 1.6 -------------- - -- `#535 `__ Markdown - checks are incompatible with default runner version -- `#550 `__ Makefile - doesn't allow for :vale-ignore:`pymarkdownlnt` to exit with a status code of 1 - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this -release: - -:literalref:`akcano `, -:literalref:`AnneCYH `, -:literalref:`arturo-seijas `, -:literalref:`jahn-junior `, -:literalref:`odadacharles `, -:literalref:`wctaylor `, and -:literalref:`yhontyk ` diff --git a/docs/release-notes/assets/release-commit-history.svg b/docs/release-notes/assets/release-commit-history.svg deleted file mode 100644 index 436ceacb..00000000 --- a/docs/release-notes/assets/release-commit-history.svg +++ /dev/null @@ -1 +0,0 @@ -main0-e0d6fea1-ed443e82-ffbd8421.53-68e10564-f62b1a15-89c03b21.66-4dfdc497-7e634e7 \ No newline at end of file diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 71c070ae..ed195fbd 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -2,48 +2,3 @@ Release notes ============= - -This page lists the notes for past releases of Canonical's Sphinx Starter Pack, which -summarize new features, bug fixes and breaking changes in each version. It also contains -the release and support policies for the starter pack. - - -Latest release --------------- - -- :ref:`release-1.6` - - -Past releases -------------- - -- :ref:`release-1.5` -- :ref:`release-1.4` - - -Release versioning ------------------- - -Starter pack 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:: - :header-rows: 1 - - * - Version - - Example - - Signifies - * - Major - - **1**.3 - - Improvements that aren't backward-compatible. - * - Minor - - 1.\ **3** - - New or improved features that are simple to adopt and backward-compatible. - - -.. toctree:: - :hidden: - - 1.6 <1.6> - 1.5 <1.5> - 1.4 <1.4> diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst deleted file mode 100644 index de8a5ad5..00000000 --- a/docs/set-up-a-new-project.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _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. - -.. _initial-setup: - -Copy the starter pack -===================== - -If you're starting a new project, `copy the starter pack as a template repository `__. - -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: - -* the entire :file:`docs` directory -* :file:`.readthedocs.yaml` (configuration for the building on Read the Docs) -* the entire :file:`.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. - -Remove the files that can't be reused: - -- :file:`CONTRIBUTING.md` -- :file:`.github/CODEOWNERS` -- :file:`.github/workflows/test-starter-pack.yml` - -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. - - -Build and run the local server -============================== - -Building the documentation requires ``make``, ``python3``, ``python3-venv``, ``python3-pip``. - -In :file:`docs`, run:: - - 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/`. - -The server watches the source files, including :file:`docs/conf.py`, 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 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. - -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: - - .. code-block:: rest - :caption: reStructuredText title example - - 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: - - .. 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``. - - The ``toctree`` block will now look like this: - - .. code-block:: rest - - .. toctree:: - :hidden: - :maxdepth: 2 - - Documentation checks - style-guide - style-guide-myst - 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     ``. - - -Configure settings -================== - -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. - - -Pre-commit hooks (optional) -=========================== - -Use `pre-commit `_ hooks with the starter pack -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/_dev/`: - -.. 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. - -To apply the configuration, install the starter pack hooks, for instance:: - - pre-commit install --config docs/_dev/.pre-commit-config.yaml - - -After that, you should see the checks running with every commit:: - - git commit -m 'add spelling errors' - - Run make spelling.......................................................Failed - Run make linkcheck......................................................Passed - Run make woke...........................................................Passed diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 00000000..48020555 --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,4 @@ +.. _tutorials: + +Tutorials +=========