From debd9cf9b1f7b63885e28699cdff0ba634f3320e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Sawicz?= Date: Thu, 25 Sep 2025 11:22:02 +0200 Subject: [PATCH 1/2] pre-commit: add initial config and workflow --- .github/workflows/pre-commit.yaml | 24 ++++++++++++++++++++++ .pre-commit-config.yaml | 34 +++++++++++++++++++++++++++++++ CHANGELOG.md | 2 ++ README.md | 8 ++++++++ 4 files changed, 68 insertions(+) create mode 100644 .github/workflows/pre-commit.yaml create mode 100644 .pre-commit-config.yaml diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml new file mode 100644 index 00000000..978d1173 --- /dev/null +++ b/.github/workflows/pre-commit.yaml @@ -0,0 +1,24 @@ +name: PreCommit + +on: + pull_request: + push: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + PreCommit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v6 + with: + python-version: 3.x + - uses: pre-commit/action@v3.0.1 + - uses: pre-commit-ci/lite-action@v1.1.0 + if: always() + with: + msg: "pre-commit: apply automatic fixes" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..d68ff833 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,34 @@ +# Recommended workflow: +# - `git add --verbose --patch` to stage changes +# - `git commit` to commit them +# - rinse and repeat, if pre-commit wants / applied changes +# +# To limit impact to just the `docs` subfolder, uncomment the below +# files: ^docs/ + +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-added-large-files + +- repo: https://github.com/executablebooks/mdformat + rev: 0.7.22 + hooks: + - id: mdformat + additional_dependencies: + - mdformat-black + - mdformat-beautysh + - mdformat-gfm + - mdformat-myst + - setuptools # Necessary until beautysh fix their stuff, see: https://github.com/hukkin/mdformat/issues/442 + +- repo: https://github.com/jackdewinter/pymarkdown + rev: v0.9.32 + hooks: + - id: pymarkdown + args: + - --config=docs/.sphinx/.pymarkdown.json + - fix diff --git a/CHANGELOG.md b/CHANGELOG.md index ceac5966..a6394c26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,12 @@ ## Upcoming * Changes metrics script to a less brittle Python script +* Adds pre-commit configuration for automatic fixes and checks ### Added * `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) +* `.pre-commit-config.py` ## Changed diff --git a/README.md b/README.md index e74fa995..3000e9df 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,12 @@ This directory contains files used for documentation build checks via GitHub's C The file `test-starter-pack.yml` tests the functionality of the starter pack project. +### `.pre-commit-config.yaml` + +This file has configuration for [pre-commit](pre-commit) checks for automatic fixes and checks, local or in CI. + +It can apply the automatic fixes directly through [the GitHub App](pre-commit-ci-lite) - configure it to enable access to repositories you want it on. + ## Contributing We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request. @@ -39,3 +45,5 @@ Please read and sign our [Contributor Licence Agreement (CLA)] before submitting [Sphinx]: https://www.sphinx-doc.org/ [Contributor Licence Agreement (CLA)]: https://ubuntu.com/legal/contributors +[pre-commit]: https://pre-commit.com/ +[pre-commit-ci-lite]: https://github.com/apps/pre-commit-ci-lite From fdd1bfc888d9b8d36e35f70ad51cf39d136e0236 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Sawicz?= Date: Thu, 25 Sep 2025 11:40:01 +0200 Subject: [PATCH 2/2] pre-commit: apply automatic fixes --- .github/CODEOWNERS | 2 +- .github/pull_request_template.md | 2 +- CHANGELOG.md | 111 +++++++------ LICENSE | 2 +- README.md | 14 +- docs/.sphinx/get_vale_conf.py | 16 +- docs/conf.py | 2 +- docs/how-to/build.rst | 2 +- docs/how-to/contributing-myst.md | 8 +- docs/how-to/contributing.rst | 4 +- docs/how-to/customise-pdf.rst | 16 +- docs/how-to/customise.rst | 5 +- docs/how-to/edit.rst | 6 +- docs/how-to/migrate-from-pre-extension.rst | 19 ++- docs/how-to/rtd.rst | 2 +- docs/how-to/set-up-sitemaps.rst | 6 +- docs/reference/automatic_checks.rst | 4 +- .../automatic_checks_inclusivelanguage.rst | 4 +- docs/reference/automatic_checks_spelling.rst | 2 +- .../reference/automatic_checks_styleguide.rst | 6 +- docs/reference/myst-syntax-reference.md | 149 +++++++++++------- docs/reference/removed-url-check.rst | 4 +- docs/reuse/substitutions.txt | 2 +- docs/reuse/substitutions.yaml | 2 +- docs/tutorial/index.rst | 2 - docs/tutorial/set-up-automated-testing.rst | 32 ++-- docs/tutorial/set-up.rst | 2 +- 27 files changed, 225 insertions(+), 201 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c848415c..86df0328 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,7 +1,7 @@ # Codeowners for this repository. # Guidance and syntax is covered in # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners -# +# # Important: The last match takes precedence. # Development reviewers diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ebabf946..cd781a5a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ - [ ] Have you updated `CHANGELOG.md` with relevant non-documentation file changes? - [ ] Have you updated the documentation for this change? ------ +______________________________________________________________________ diff --git a/CHANGELOG.md b/CHANGELOG.md index a6394c26..873438a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,64 +2,63 @@ ## Upcoming -* Changes metrics script to a less brittle Python script -* Adds pre-commit configuration for automatic fixes and checks +- Changes metrics script to a less brittle Python script +- Adds pre-commit configuration for automatic fixes and checks ### Added -* `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) -* `.pre-commit-config.py` +- `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) +- `.pre-commit-config.py` ## Changed -* `docs/Makefile` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) -* `docs/conf.py` [#429](https://github.com/canonical/sphinx-docs-starter-pack/pull/429) -* `docs/.sphinx/update_sp.py` [#425](https://github.com/canonical/sphinx-docs-starter-pack/pull/425) -* `.github/workflows/check-removed-urls.yml` [#437](https://github.com/canonical/sphinx-docs-starter-pack/pull/437) +- `docs/Makefile` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) +- `docs/conf.py` [#429](https://github.com/canonical/sphinx-docs-starter-pack/pull/429) +- `docs/.sphinx/update_sp.py` [#425](https://github.com/canonical/sphinx-docs-starter-pack/pull/425) +- `.github/workflows/check-removed-urls.yml` [#437](https://github.com/canonical/sphinx-docs-starter-pack/pull/437) ### Removed -* `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) +- `docs/.sphinx/metrics/build_metrics.py` [#373](https://github.com/canonical/sphinx-docs-starter-pack/pull/373) ## 1.2.0 -* Replaces spelling check with Vale. -* Fixes the Markdown linting GitHub action and adds a `make lint-md` check. -* Fixes the download branch name in the update script. -* Adds a check for removed URLs. +- Replaces spelling check with Vale. +- Fixes the Markdown linting GitHub action and adds a `make lint-md` check. +- Fixes the download branch name in the update script. +- Adds a check for removed URLs. ### Added -* `docs/.sphinx/.pymarkdown.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `.github/workflows/check-removed-urls.yml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `docs/.sphinx/.pymarkdown.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) +- `.github/workflows/check-removed-urls.yml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) ### Changed -* `docs/.sphinx/update_sp.py` [#397](https://github.com/canonical/sphinx-docs-starter-pack/pull/397) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `.github/workflows/markdown-style-checks.yml` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `docs/Makefile` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/requirements.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/.sphinx/get_vale_conf.py` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `docs/.sphinx/update_sp.py` [#397](https://github.com/canonical/sphinx-docs-starter-pack/pull/397) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `.github/workflows/markdown-style-checks.yml` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) +- `docs/Makefile` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `docs/requirements.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `docs/.sphinx/get_vale_conf.py` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) ### Removed -* `docs/.sphinx/.markdownlint.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) -* `docs/.sphinx/.wordlist.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) -* `docs/.sphinx/spellingcheck.yaml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) - +- `docs/.sphinx/.markdownlint.json` [#379](https://github.com/canonical/sphinx-docs-starter-pack/pull/379) +- `docs/.sphinx/.wordlist.txt` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) +- `docs/.sphinx/spellingcheck.yaml` [#410](https://github.com/canonical/sphinx-docs-starter-pack/pull/410) ## 1.1.0 -* Adds sitemap support. -* Simplifies vale binary download & install. -* Leaves vale install output in STDOUT to reveal potential problems. -* Improves update logic. -* Update Makefile logic +- Adds sitemap support. +- Simplifies vale binary download & install. +- Leaves vale install output in STDOUT to reveal potential problems. +- Improves update logic. +- Update Makefile logic ### Changed -* `docs/conf.py` [#389](https://github.com/canonical/sphinx-docs-starter-pack/pull/389) -* `docs/requirements.txt`(https://github.com/canonical/sphinx-docs-starter-pack/pull/389) +- `docs/conf.py` [#389](https://github.com/canonical/sphinx-docs-starter-pack/pull/389) +- `docs/requirements.txt`(https://github.com/canonical/sphinx-docs-starter-pack/pull/389) ## 1.0.1 @@ -67,9 +66,9 @@ Fixes an issue with Vale implementation, and adds words to main wordlist. ### Changed -* `docs/Makefile` [852c19b](https://github.com/canonical/sphinx-docs-starter-pack/commit/852c19bf162e4697d7f36b49e8bc36ad71302216) -* `docs/.sphinx/.wordlist.txt` [#367](https://github.com/canonical/sphinx-docs-starter-pack/pull/367) -* `docs/.sphinx/get_vale_conf.py` [#358](https://github.com/canonical/sphinx-docs-starter-pack/pull/358) +- `docs/Makefile` [852c19b](https://github.com/canonical/sphinx-docs-starter-pack/commit/852c19bf162e4697d7f36b49e8bc36ad71302216) +- `docs/.sphinx/.wordlist.txt` [#367](https://github.com/canonical/sphinx-docs-starter-pack/pull/367) +- `docs/.sphinx/get_vale_conf.py` [#358](https://github.com/canonical/sphinx-docs-starter-pack/pull/358) ## 1.0.0 @@ -78,24 +77,24 @@ starter pack based documentation sets. ### Added -* `CHANGELOG.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `.github/pull_request_template.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/version` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/update_sp.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `CHANGELOG.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `.github/pull_request_template.md` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/.sphinx/version` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/.sphinx/update_sp.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) ### Changed -* `.readthedocs.yaml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/.sphinx/.markdownlint.json` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/Makefile` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/conf.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) -* `docs/requirements.txt` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `.readthedocs.yaml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `.github/workflows/sphinx-python-dependency-build-checks.yml` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/.sphinx/.markdownlint.json` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/Makefile` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/conf.py` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `docs/requirements.txt` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) ### Removed -* `.wokeignore` [#363](https://github.com/canonical/sphinx-docs-starter-pack/pull/363) -* `docs/.sphinx/_static/project_specific.css` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) +- `.wokeignore` [#363](https://github.com/canonical/sphinx-docs-starter-pack/pull/363) +- `docs/.sphinx/_static/project_specific.css` [#357](https://github.com/canonical/sphinx-docs-starter-pack/pull/357) ## pre-version @@ -104,7 +103,7 @@ updates. ### Added -* All files +- All files ## VERSION @@ -112,18 +111,18 @@ updates. ### Added -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} ### Changed -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} ### Removed -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} -* {File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} +- \{File} {[Commit number](https://www.github.com) or [PR](https://www.github.com)} diff --git a/LICENSE b/LICENSE index 31081ad4..fb590db9 100644 --- a/LICENSE +++ b/LICENSE @@ -691,4 +691,4 @@ 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 +Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. diff --git a/README.md b/README.md index 3000e9df..158122b8 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ The Documentation starter pack includes: -* A bundled [Sphinx] theme, configuration, and extensions -* Support for both reStructuredText (reST) and MyST Markdown -* Build checks for links, spelling, and inclusive language -* Customisation support layered over a core configuration +- A bundled [Sphinx] theme, configuration, and extensions +- Support for both reStructuredText (reST) and MyST Markdown +- Build checks for links, spelling, and inclusive language +- Customisation support layered over a core configuration See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/ @@ -43,7 +43,5 @@ Please read and sign our [Contributor Licence Agreement (CLA)] before submitting -[Sphinx]: https://www.sphinx-doc.org/ -[Contributor Licence Agreement (CLA)]: https://ubuntu.com/legal/contributors -[pre-commit]: https://pre-commit.com/ -[pre-commit-ci-lite]: https://github.com/apps/pre-commit-ci-lite +[contributor licence agreement (cla)]: https://ubuntu.com/legal/contributors +[sphinx]: https://www.sphinx-doc.org/ diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py index e2a81c08..13e7966f 100644 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/.sphinx/get_vale_conf.py @@ -31,12 +31,12 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): """ Clone the repository to a temporary directory and copy required files - + Args: file_source_dest: dictionary of file paths to copy from the repository, and their destination paths overwrite: boolean flag to overwrite existing files in the destination - + Returns: bool: True if all files were copied successfully, False otherwise """ @@ -52,8 +52,8 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): try: result = subprocess.run( - clone_cmd, - capture_output=True, + clone_cmd, + capture_output=True, text=True, check=True ) @@ -73,7 +73,7 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): continue if not copy_files_to_path(source_path, dest, overwrite): - is_copy_success = False + is_copy_success = False logging.error("Failed to copy %s to %s", source_path, dest) # Clean up temporary directory @@ -85,12 +85,12 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False): def copy_files_to_path(source_path, dest_path, overwrite=False): """ Copy a file or directory from source to destination - + Args: source_path: Path to the source file or directory dest_path: Path to the destination overwrite: Boolean flag to overwrite existing files in the destination - + Returns: bool: True if copy was successful, False otherwise """ @@ -138,7 +138,7 @@ def main(): # Parse command line arguments, default to overwrite_enabled = True overwrite_enabled = not parse_arguments().no_overwrite - # Download into /tmp through git clone + # Download into /tmp through git clone if not clone_repo_and_copy_paths(vale_files_dict, overwrite=overwrite_enabled): logging.error("Failed to download files from repository") return 1 diff --git a/docs/conf.py b/docs/conf.py index 61524fb6..069a7475 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -149,7 +149,7 @@ # TODO: To enable listing contributors on individual pages, set to True "display_contributors": False, - # Required for feedback button + # Required for feedback button 'github_issues': 'enabled', } diff --git a/docs/how-to/build.rst b/docs/how-to/build.rst index 59fce699..d57ee68b 100644 --- a/docs/how-to/build.rst +++ b/docs/how-to/build.rst @@ -101,7 +101,7 @@ 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. diff --git a/docs/how-to/contributing-myst.md b/docs/how-to/contributing-myst.md index 28383654..ec980259 100644 --- a/docs/how-to/contributing-myst.md +++ b/docs/how-to/contributing-myst.md @@ -3,6 +3,7 @@ orphan: true --- + # How to contribute @@ -137,7 +138,7 @@ 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: + message, and push again: ```{code-block} none git commit --amend --no-edit -n -S @@ -145,8 +146,9 @@ message, and push again: ``` 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). + 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 diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst index fa7db3f1..d0837ecd 100644 --- a/docs/how-to/contributing.rst +++ b/docs/how-to/contributing.rst @@ -146,10 +146,10 @@ 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: diff --git a/docs/how-to/customise-pdf.rst b/docs/how-to/customise-pdf.rst index 7a2328f8..7de065e9 100644 --- a/docs/how-to/customise-pdf.rst +++ b/docs/how-to/customise-pdf.rst @@ -52,7 +52,7 @@ For more details, see `latex_documents :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: diff --git a/docs/how-to/set-up-sitemaps.rst b/docs/how-to/set-up-sitemaps.rst index 10adc615..79c62032 100644 --- a/docs/how-to/set-up-sitemaps.rst +++ b/docs/how-to/set-up-sitemaps.rst @@ -1,7 +1,7 @@ Set up Sphinx sitemaps ============================= -It is recommended to generate a sitemap for your documentation using the +It is recommended to generate a sitemap for your documentation using the `sphinx-sitemap `_ extension. @@ -19,7 +19,7 @@ Sitemap prerequisites 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 +changes the builder, the links generated by the sitemap will be malformed. Either update to the latest version of the Starter Pack or ensure your project's recipes use the ``dirhtml`` builder, not ``html``. @@ -74,7 +74,7 @@ Or, if the version is set with the ``version`` key in your configuration file: sitemap_url_scheme = "{version}{link}" To read from the provided RTD environment variable:: - + if 'READTHEDOCS_VERSION' in os.environ: version = os.environ["READTHEDOCS_VERSION"] sitemap_url_scheme = '{version}{link}' diff --git a/docs/reference/automatic_checks.rst b/docs/reference/automatic_checks.rst index a159adbf..86d822fa 100644 --- a/docs/reference/automatic_checks.rst +++ b/docs/reference/automatic_checks.rst @@ -16,9 +16,9 @@ The following checks are available: Install prerequisite software ----------------------------- -Some of the tools used by the automatic checks require ``npm``. Install ``npm`` using the appropriate method for your operating system through one of the following methods: +Some of the tools used by the automatic checks require ``npm``. Install ``npm`` using the appropriate method for your operating system through one of the following methods: -* Your preferred package manager +* Your preferred package manager * By following the `node version manager installation process `_ * For Debian and Ubuntu Linux distributions, the ``sudo apt install npm`` command diff --git a/docs/reference/automatic_checks_inclusivelanguage.rst b/docs/reference/automatic_checks_inclusivelanguage.rst index 4c7c7ece..fbfdfc4c 100644 --- a/docs/reference/automatic_checks_inclusivelanguage.rst +++ b/docs/reference/automatic_checks_inclusivelanguage.rst @@ -38,7 +38,7 @@ For instance:: Vale will lint the displayed text of a link, not the URL of a link. If you wish to use a link that contains non-inclusive language, use appropriate link - text with the syntax appropriate for your source file. + text with the syntax appropriate for your source file. Exempt a word globally ~~~~~~~~~~~~~~~~~~~~~~ @@ -77,4 +77,4 @@ To turn Vale off entirely for a section of |RST|:: This text will be ignored. - .. vale on \ No newline at end of file + .. vale on diff --git a/docs/reference/automatic_checks_spelling.rst b/docs/reference/automatic_checks_spelling.rst index b778c0da..c3617af5 100644 --- a/docs/reference/automatic_checks_spelling.rst +++ b/docs/reference/automatic_checks_spelling.rst @@ -32,4 +32,4 @@ In this case, you can use the ``:vale-ignore:`` role, and ensure your configurat rst_prolog = """ .. role:: vale-ignore :class: vale-ignore - """ \ No newline at end of file + """ diff --git a/docs/reference/automatic_checks_styleguide.rst b/docs/reference/automatic_checks_styleguide.rst index 12255be4..fb41c402 100644 --- a/docs/reference/automatic_checks_styleguide.rst +++ b/docs/reference/automatic_checks_styleguide.rst @@ -79,7 +79,7 @@ For Markdown: ```` .. note:: - + This should not be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. For |RST|: @@ -91,7 +91,7 @@ For |RST|: This content will be ignored by Vale. -.. note:: +.. note:: The `.. class::` directive does not need to encapsulate content, it applies to the next logical block (which can be another directive or even a paragraph of content). @@ -109,4 +109,4 @@ Use the ``:vale-ignore:`` role to ignore specific words inline, but first ensure The spelling check might still flag some terms that contain hyphens or spaces. - For example, "Juju 3" was unable to be ignored by this method, and `needed to be added to the a specific exception within a rule `_. \ No newline at end of file + For example, "Juju 3" was unable to be ignored by this method, and `needed to be added to the a specific exception within a rule `_. diff --git a/docs/reference/myst-syntax-reference.md b/docs/reference/myst-syntax-reference.md index 29dea71e..8dab9ec5 100644 --- a/docs/reference/myst-syntax-reference.md +++ b/docs/reference/myst-syntax-reference.md @@ -2,10 +2,7 @@ relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) myst: substitutions: - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" + advanced_reuse_key: 'This is a substitution that includes a code block: ``` code block ```' --- (myst_style_guide)= @@ -26,8 +23,9 @@ For general style conventions, see the [Canonical Documentation Style Guide](htt ## Headings ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Description * - `# Title` @@ -51,8 +49,9 @@ Adhere to the following conventions: ## Inline formatting ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - `` {guilabel}`UI element` `` @@ -81,13 +80,16 @@ Adhere to the following conventions: 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 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -126,9 +128,10 @@ You can specify the code language after the back ticks to enforce a specific lex To include back ticks in a code block, increase the number of surrounding back ticks: -`````{list-table} - :header-rows: 1 - +``````{list-table} +--- +header-rows: 1 +--- * - Input - Output * - @@ -147,7 +150,7 @@ To include back ticks in a code block, increase the number of surrounding back t ```` -````` +`````` ### Terminal output @@ -157,8 +160,9 @@ In addition, including a terminal view can help break up a long text and make it To show a terminal view, use the following directive: `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -205,8 +209,9 @@ 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 - +--- +header-rows: 1 +--- * - Input - Output * - `[Canonical website](https://canonical.com)` @@ -220,8 +225,9 @@ You can also use just the URL, but this will usually cause issues with the spell To display a URL as text and prevent it from being linked, add a ``: ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - `https://canonical.com` @@ -235,22 +241,27 @@ 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) +``` +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 +``` +discourse: 12345 +``` #### YouTube links To add a link to a YouTube video, use the following directive: `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -285,8 +296,9 @@ You can add targets at any place in the documentation. However, if there is no h (a_random_target_myst)= ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output - Output on GitHub @@ -325,8 +337,9 @@ If a documentation page does not have a target, you can still reference it by us Use MyST syntax to automatically extract the link text. When overriding the link text, use Markdown syntax. ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output - Output on GitHub @@ -391,8 +404,9 @@ To exclude pages from the build, add them to the `custom_excludes` variable in t ## Lists ````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ``` @@ -438,8 +452,9 @@ Adhere to the following conventions: ### Definition lists ````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ``` @@ -464,8 +479,9 @@ See the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restru Both markups result in the following output: ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Header 1 - Header 2 * - Cell 1 @@ -507,8 +523,9 @@ See [list tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#l ## Notes `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -555,9 +572,10 @@ Adhere to the following conventions: ## Images -````{list-table} - :header-rows: 1 - +`````{list-table} +--- +header-rows: 1 +--- * - Input - Output * - ``` @@ -578,7 +596,7 @@ Adhere to the following conventions: Figure caption ``` -```` +````` Adhere to the following conventions: @@ -599,8 +617,9 @@ 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`: ```{code-block} python - :caption: "{spellexception}`conf.py`" - + --- + caption: '{spellexception}`conf.py`' + --- import os import yaml @@ -612,12 +631,15 @@ Substitutions can be defined in the following locations: ``` ```{code-block} yaml - :caption: "{spellexception}`reuse/substitutions.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: ```` @@ -640,8 +662,9 @@ You can combine both options by defining a default substitution in `reuse/substi The definitions from the above examples are rendered as follows: ```{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - `{{version_number}}` @@ -669,8 +692,9 @@ You cannot put any targets into the content that is being reused (because refere By combining file inclusion and substitutions, you can even replace parts of the included text. `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -696,7 +720,7 @@ By combining file inclusion and substitutions, you can even replace parts of the Adhere to the following convention: - File inclusion does not work on GitHub. Therefore, always add a comment linking to the included file. -- Files that only contain text that is reused somewhere else should be placed in the {file}`reuse` folder and end with the extension ``.txt`` to distinguish them from normal content files. +- 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 @@ -704,8 +728,9 @@ Adhere to the following convention: 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 - +--- +header-rows: 1 +--- * - Input - Output * - ````` @@ -747,8 +772,9 @@ The recommended way of creating tabs is to use the tabs that the [Sphinx design] Alternatively, you can use the [Sphinx tabs](https://sphinx-tabs.readthedocs.io/en/latest/) extension, which is also enabled by default. This was previously recommended due to limitations in Sphinx Design that are now fixed. ``````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ````` @@ -788,8 +814,9 @@ Alternatively, you can use the [Sphinx tabs](https://sphinx-tabs.readthedocs.io/ There is no support for details sections in MyST, but you can insert HTML to create them. ````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ``` @@ -813,8 +840,9 @@ There is no support for details sections in MyST, but you can insert HTML to cre You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file. `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output * - ```` @@ -840,8 +868,9 @@ You can define glossary terms in any file. Ideally, all terms should be collecte ## More useful markup `````{list-table} - :header-rows: 1 - +--- +header-rows: 1 +--- * - Input - Output - Description diff --git a/docs/reference/removed-url-check.rst b/docs/reference/removed-url-check.rst index fc3522e3..a2bea7de 100644 --- a/docs/reference/removed-url-check.rst +++ b/docs/reference/removed-url-check.rst @@ -7,8 +7,8 @@ The starter pack includes a GitHub action to identify when page URLs 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 changing the RTD +This does not cover higher-level changes to URL paths, such as changing the RTD project name, or language and versioning structure provided by RTD. This check is available to ensure that redirects are implemented when pages are -moved, or appropriate information can be provided when anything is removed. \ No newline at end of file +moved, or appropriate information can be provided when anything is removed. diff --git a/docs/reuse/substitutions.txt b/docs/reuse/substitutions.txt index 307b5f2e..6d0e51bf 100644 --- a/docs/reuse/substitutions.txt +++ b/docs/reuse/substitutions.txt @@ -4,4 +4,4 @@ that uses basic **markup**. .. |site_link| replace:: Website link -.. _site_link: https://example.com \ No newline at end of file +.. _site_link: https://example.com diff --git a/docs/reuse/substitutions.yaml b/docs/reuse/substitutions.yaml index 0c2958d2..be8526d3 100644 --- a/docs/reuse/substitutions.yaml +++ b/docs/reuse/substitutions.yaml @@ -1,4 +1,4 @@ # Key/value substitutions to use within the Sphinx doc. {version_number: "0.1.0", formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} \ No newline at end of file + site_link: "[Website link](https://example.com)"} diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 1955b292..2ed1a81e 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -10,5 +10,3 @@ Tutorials for using Sphinx and Read the Docs to host and test your documentation set-up set-up-automated-testing - - diff --git a/docs/tutorial/set-up-automated-testing.rst b/docs/tutorial/set-up-automated-testing.rst index cb5a7432..c6202def 100644 --- a/docs/tutorial/set-up-automated-testing.rst +++ b/docs/tutorial/set-up-automated-testing.rst @@ -16,7 +16,7 @@ your tutorial uses the same commands that Spread is testing. **What you'll need** -* `Multipass `_ installed on your machine +* `Multipass `_ installed on your machine * `Spread `_ installed on your machine .. warning:: @@ -38,7 +38,7 @@ and change into it. This is the root directory of your example project. Inside the ``spread_test_example`` directory, create the ``tests`` directory using ``mkdir tests`` and change into it. This directory can hold materials for multiple -Spread tests. +Spread tests. Under the ``tests`` directory, create a new directory ``example_tutorial`` to store the files for a "Hello, world" Spread test. This test consists of two files: @@ -51,7 +51,7 @@ named ``example_bash_script.sh``: .. code-block:: - echo -e '#! /usr/bin/bash\n\necho "Hello, world!"' > example_bash_script.sh + echo -e '#! /usr/bin/bash\n\necho "Hello, world!"' > example_bash_script.sh Now let's create a ``task.yaml`` file. This file holds all the commands the user will run in your tutorial. @@ -76,16 +76,16 @@ into a new file ``task.yaml``: execute: | # [docs:make-bash-executable] chmod +x example_bash_script.sh - # [docs:make-bash-executable-end] + # [docs:make-bash-executable-end] # [docs:execute-bash-script] bash example_bash_script.sh - # [docs:execute-bash-script-end] + # [docs:execute-bash-script-end] The ``summary`` section contains a brief description of your tutorial, and the ``execute`` section contains all the commands that your tutorial uses. The ``kill-timeout`` option has a default of 10 minutes and doesn't need to be -included if your test will complete in that time frame. +included if your test will complete in that time frame. By wrapping commands with comments in the form of ``# [docs:example-wrapping-command]`` and ``# [docs-example-wrapping-command-end]``, @@ -96,11 +96,11 @@ Create the tutorial file Now we have everything we need to create the tutorial file itself. `ReStructuredText (.rst)`_ is used for the tutorial file format; `MyST-Markdown`_ -can also be used. +can also be used. In ``spread_test_example/tests/example_tutorial``, create a text file named ``example_tutorial.rst``. To add a title for your tutorial, copy the -block below to this file. +block below to this file. .. code-block:: rst :caption: ~/spread_test_example/tests/example_tutorial/example_tutorial.rst @@ -110,7 +110,7 @@ block below to this file. In this file, we can use Sphinx's ``literalinclude`` directives to feed the Spread test materials directly into our tutorial. This way, we guarantee -that the Spread test is testing the exact commands that appear in the tutorial. +that the Spread test is testing the exact commands that appear in the tutorial. Let's start with the bash script. In the mock tutorial, we want the the reader to create the file themselves, so let's use that language in ``example_tutorial.rst`` @@ -145,7 +145,7 @@ appear in our ``task.yaml`` file, again using the ``literalinclude`` directive: Create a new file ``example_bash_script.sh`` with the following contents: .. literalinclude:: example_bash_script.sh - :language: bash + :language: bash Make the script executable: @@ -212,7 +212,7 @@ The ``suites`` section is how we tell Spread about the various Spread tests in our project. We tell Spread to look in the ``tests`` directory for all Spread tests (which it will only find one, ``example_tutorial``). We also use the ``suites`` section to tell Spread about the systems we want Spread to test. -For our mock tutorial, we will use Ubuntu 24.04. +For our mock tutorial, we will use Ubuntu 24.04. Configure the Spread test to use Multipass ------------------------------------------ @@ -220,7 +220,7 @@ Configure the Spread test to use Multipass Each job in Spread has a backend, or a way to obtain a machine on which to run your Spread test. The `Spread repository `_ contains more information on backends like Google or QEMU, but let's set up Multipass as -a backend to run local tests. +a backend to run local tests. Include the following ``backends`` section of ``spread.yaml`` between the ``path`` and ``suites`` sections: @@ -231,7 +231,7 @@ Include the following ``backends`` section of ``spread.yaml`` between the ``path project: spread_test_example - path: /spread_test_example + path: /spread_test_example backends: multipass: @@ -279,7 +279,7 @@ Include the following ``backends`` section of ``spread.yaml`` between the ``path The ``backends`` section contains the following sections: * The backend is designated as ``type: adhoc`` as we are explicitly - scripting the procedure to allocate and discard the Multipass VM. + scripting the procedure to allocate and discard the Multipass VM. * In the ``allocate`` section, we define the image and name of the VM, launch the VM, and then set up the proper SSH permissions so that Spread can log in (via root) into the VM and insert the Spread test. We also must tell Spread about the @@ -303,7 +303,7 @@ test for ``example_tutorial``: :dir: spread_test_example :input: spread --list - multipass:ubuntu-24.04-64:tests/example_tutorial + multipass:ubuntu-24.04-64:tests/example_tutorial Now let's run the Spread test for ``example_tutorial``: @@ -353,7 +353,7 @@ Next steps Congratulations! You set up the materials needed to run a Spread test locally using Multipass with commands that explicitly appear in a Sphinx-based tutorial. This -section provides additional examples of Spread tests: +section provides additional examples of Spread tests: * `Spread tests included in Rockcraft documentation `_ * `Spread tests included in Charmcraft documentation `_ diff --git a/docs/tutorial/set-up.rst b/docs/tutorial/set-up.rst index 86e72d99..fde4e186 100644 --- a/docs/tutorial/set-up.rst +++ b/docs/tutorial/set-up.rst @@ -20,7 +20,7 @@ If you already have a project, download the following files from the repository * :file:`.wokeignore` (configuration for the Woke tool) * the entire :file:`.github/workflows` directory -After cloning or copying the starter pack, you **must** delete :file:`.github/workflows/test-starter-pack.yml` from your repository, as this workflow is specific to testing the starter pack itself and should not be included in your project. Optionally, you can also delete +After cloning or copying the starter pack, you **must** delete :file:`.github/workflows/test-starter-pack.yml` from your repository, as this workflow is specific to testing the starter pack itself and should not be included in your project. Optionally, you can also delete :file:`.github/workflows/sphinx-python-dependency-build-checks.yml` and :file:`.github/workflows/markdown-style-checks.yml` if you do not need these workflows in your project. Build and run the local server