From 434415246a3c17958b9cde5fab24b027e4a7b74d Mon Sep 17 00:00:00 2001 From: nhennigan Date: Wed, 1 Apr 2026 14:46:15 -0700 Subject: [PATCH 1/6] Remove reuse dir Remove the reuse directory. Update all links from links.txt into the individual files. Move the substitutions to the conf.py. Update the docs that pointed to the reuse dir components. Move mermaid code and component code to assets dir --- docs/conf.py | 26 ++++++++-- .../assets}/components.yaml | 10 ++-- docs/{reuse => how-to/assets}/mermaid.txt | 0 docs/how-to/configure-your-project.rst | 10 ++++ docs/how-to/contributing.rst | 3 ++ .../interactive-tables.rst | 7 ++- .../mermaid-diagrams.md | 8 ++-- docs/how-to/publish-on-rtd.rst | 7 +++ .../legacy-starter-pack.rst | 2 +- docs/index.rst | 3 ++ .../automatic_checks_accessibility.rst | 47 +++++++++++++++++++ docs/reference/index.rst | 2 + docs/reference/myst-syntax.md | 14 ++++-- docs/reference/rst-syntax.rst | 11 ++++- docs/reuse/links.txt | 46 ------------------ docs/reuse/substitutions.txt | 7 --- docs/reuse/substitutions.yaml | 4 -- docs/set-up-a-new-project.rst | 3 ++ 18 files changed, 132 insertions(+), 78 deletions(-) rename docs/{reuse => explanation/assets}/components.yaml (89%) rename docs/{reuse => how-to/assets}/mermaid.txt (100%) create mode 100644 docs/reference/automatic_checks_accessibility.rst delete mode 100644 docs/reuse/links.txt delete mode 100644 docs/reuse/substitutions.txt delete mode 100644 docs/reuse/substitutions.yaml diff --git a/docs/conf.py b/docs/conf.py index b0aad1f5..82bd3eb1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,7 +29,7 @@ # 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 +# 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}" @@ -131,7 +131,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', # Inherit the author value @@ -320,10 +320,18 @@ # 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. +# rst_epilog = """ +# .. include:: reuse/substitutions.txt +# """ rst_epilog = """ -.. include:: /reuse/links.txt -.. include:: /reuse/substitutions.txt +.. |RST| replace:: :abbr:`reST (reStructuredText)` +.. |version_number| replace:: 0.1.0 +.. |rest_text| replace:: *Multi-line* text + that uses basic **markup**. +.. |site_link| replace:: Website link +.. _site_link: https://example.com """ # Feedback button at the top; enabled by default @@ -367,10 +375,18 @@ 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. diff --git a/docs/reuse/components.yaml b/docs/explanation/assets/components.yaml similarity index 89% rename from docs/reuse/components.yaml rename to docs/explanation/assets/components.yaml index d9755648..75494524 100644 --- a/docs/reuse/components.yaml +++ b/docs/explanation/assets/components.yaml @@ -6,7 +6,7 @@ documentation_architecture: A["Source Files
(.rst or .md)"] -->|provides content to| C[Sphinx] B["Configuration
(docs/conf.py)"] -->|provides settings to| C C -->|generates| D[Built HTML Pages] - rendered_image: "../explanation/assets/sphinx.png" + rendered_image: "sphinx.png" - diagram_name: "Python environment" description: "The relationship between the host system and the virtual environment." @@ -23,7 +23,7 @@ documentation_architecture: end Sphinx -->|builds| HTML[HTML] end - rendered_image: "../explanation/assets/python-starter-pack.png" + rendered_image: "python-starter-pack.png" - diagram_name: "Extensions" description: "How built-in and third-party extensions are integrated and activated via requirements and conf.py." @@ -38,7 +38,7 @@ documentation_architecture: end BuiltIn -->|are activated in| Conf[/"Project configuration file (docs/conf.py)"\] ThirdParty -->|are activated in| Conf - rendered_image: "../explanation/assets/extensions.png" + rendered_image: "extensions.png" - diagram_name: "Read the Docs" description: "Details the declaration of build logic in the RTD configuration file for hosting." @@ -49,7 +49,7 @@ documentation_architecture: Python_Ver["Python version"] -->|is declared in| RTD_Conf RTD_Conf -->|defines the build logic for| RTD["Read the Docs (RTD)"] RTD -->|builds and hosts| HTML[/"HTML"\] - rendered_image: "../explanation/assets/rtd-build.png" + rendered_image: "rtd-build.png" - diagram_name: "Third-party extensions" description: "Focuses on the specific installation path for external dependencies via pip and requirements." @@ -64,4 +64,4 @@ documentation_architecture: end Python -->|installs the contents of| Reqs Reqs -->|specifies| ThirdParty - rendered_image: "../explanation/assets/third-party-extensions.png" \ No newline at end of file + rendered_image: "third-party-extensions.png" \ No newline at end of file diff --git a/docs/reuse/mermaid.txt b/docs/how-to/assets/mermaid.txt similarity index 100% rename from docs/reuse/mermaid.txt rename to docs/how-to/assets/mermaid.txt diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst index b597afb9..c21b5c8b 100644 --- a/docs/how-to/configure-your-project.rst +++ b/docs/how-to/configure-your-project.rst @@ -177,3 +177,13 @@ 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``. +.. LINKS +.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx +.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log +.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html +.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ +.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ +.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html +.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html + + diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst index cc50b4e3..bc041d1b 100644 --- a/docs/how-to/contributing.rst +++ b/docs/how-to/contributing.rst @@ -328,3 +328,6 @@ You can (and should) run the same checks locally: make spelling make linkcheck make woke + +.. LINKS +.. _Diátaxis: https://diataxis.fr/ \ No newline at end of file diff --git a/docs/how-to/optional-customisation/interactive-tables.rst b/docs/how-to/optional-customisation/interactive-tables.rst index b6e3a8fc..73969c2f 100644 --- a/docs/how-to/optional-customisation/interactive-tables.rst +++ b/docs/how-to/optional-customisation/interactive-tables.rst @@ -29,7 +29,7 @@ Make a table interactive by adding a special CSS class to the directive: .. csv-table:: :class: sphinx-datatable - :file: /reuse/animals.csv + :file: /howto/assets/animals.csv :header-rows: 1 .. tab-item:: MyST @@ -38,6 +38,9 @@ Make a table interactive by adding a special CSS class to the directive: ```{csv-table} :class: sphinx-datatable - :file: /reuse/animals.csv + :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 index f9565e40..0dc0f6c0 100644 --- a/docs/how-to/optional-customisation/mermaid-diagrams.md +++ b/docs/how-to/optional-customisation/mermaid-diagrams.md @@ -66,7 +66,7 @@ See the [Mermaid - Diagram syntax] reference for details on the syntax and custo The left-to-right flowchart below uses the default Mermaid settings. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-flowchart-start :end-before: mermaid-diagram-flowchart-end ``` @@ -75,7 +75,7 @@ The left-to-right flowchart below uses the default Mermaid settings. The timeline diagram below uses a [pre-defined Mermaid theme]. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-timeline-start :end-before: mermaid-diagram-timeline-end ``` @@ -86,7 +86,7 @@ The sequence diagram below has custom styling applied using a global CSS file. A global CSS file enables the styles to be easily applied to all sequence diagrams, based on the classes defined in your stylesheet. You can also use the global CSS file to customize the diagrams in dark mode. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-sequence-start :end-before: mermaid-diagram-sequence-end ``` @@ -95,7 +95,7 @@ You can also use the global CSS file to customize the diagrams in dark mode. The state diagram below has image-specific custom styling applied using the [`classDef` keyword]. -```{include} /reuse/mermaid.txt +```{include} /how-to/assets/mermaid.txt :start-after: mermaid-diagram-state-start :end-before: mermaid-diagram-state-end ``` diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index 417a2760..894d9e76 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -61,3 +61,10 @@ To make Read the Docs automatically build your documentation when a pull request 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. + +.. LINKS +.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html +.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html +.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs +.. _manual import: https://readthedocs.com/dashboard/import/manual/ +.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical diff --git a/docs/how-to/update-starter-packs/legacy-starter-pack.rst b/docs/how-to/update-starter-packs/legacy-starter-pack.rst index 07a299b0..ada71997 100644 --- a/docs/how-to/update-starter-packs/legacy-starter-pack.rst +++ b/docs/how-to/update-starter-packs/legacy-starter-pack.rst @@ -196,7 +196,7 @@ Assuming that all previous documentation files were in the ``docs/`` sub-directo │ └── scripts │ ├── build_metrics.sh │ └── source_metrics.sh - ├── reuse # moved to `docs/reuse` + ├── reuse # removed │ └── links.txt ├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt` ├── .gitignore diff --git a/docs/index.rst b/docs/index.rst index 98c5785f..64de298e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -60,3 +60,6 @@ The Canonical Sphinx starter pack is an open source project that warmly welcomes Release notes Contribute + +.. LINKS +.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx diff --git a/docs/reference/automatic_checks_accessibility.rst b/docs/reference/automatic_checks_accessibility.rst new file mode 100644 index 00000000..7170edf1 --- /dev/null +++ b/docs/reference/automatic_checks_accessibility.rst @@ -0,0 +1,47 @@ +.. _automatic-checks-accessibility: + +Accessibility check +=================== + +The accessibility check uses `Pa11y`_ to check for accessibility issues in the documentation output. + +It is configured to use the `Web Content Accessibility Guidelines (WCAG) 2.2`_, requiring `Level AA conformance`_. + +.. note:: + + This check is only available locally. + +Install prerequisite software +----------------------------- + +``Pa11y`` must be installed through ``npm``. If you need to install ``npm``, run the following command from any location on your system:: + + sudo apt install npm + +Once ``npm`` is installed, install ``Pa11y`` by running this command from within your documentation folder. + +.. code-block:: bash + + make pa11y-install + +Run the accessibility check +--------------------------- + +Run the following command from within your documentation folder. + +Look for accessibility issues in rendered documentation:: + + make pa11y + +Configure the accessibility check +--------------------------------- + +The :file:`pa11y.json` file in the :file:`.sphinx` folder provides basic defaults. + +To browse the available settings and options, see ``Pa11y``'s `README `_ on GitHub. + +.. LINKS +.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance +.. _Pa11y: https://pa11y.org/ +.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration + diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 346c13d5..d994b04c 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -18,3 +18,5 @@ Contents rst-syntax myst-syntax +.. LINKS +.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md index 93920910..f65e995c 100644 --- a/docs/reference/myst-syntax.md +++ b/docs/reference/myst-syntax.md @@ -695,7 +695,8 @@ To reuse sentences or paragraphs that have little markup and special formatting, Substitutions can be defined in the following locations: -- Globally, in a file named {file}`reuse/substitutions.yaml` that is loaded into the [`myst_substitutions`](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax-optional.html#substitutions-with-jinja2) variable in {file}`conf.py`: +**Globally**, in a file named {file}`reuse/substitutions.yaml` that is loaded into the [`myst_substitutions`](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax-optional.html#substitutions-with-jinja2) variable in {file}`conf.py`. Or if you have a limitied amount of substitutions, enter them directly into the +`myst_substitutions` variable in `conf.py`: ```{code-block} python :caption: "{spellexception}`conf.py`" @@ -708,6 +709,12 @@ Substitutions can be defined in the following locations: 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 @@ -717,7 +724,9 @@ Substitutions can be defined in the following locations: {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: + ``` + +**Locally**, putting the definitions at the top of a single file in the following format: ```` --- @@ -730,7 +739,6 @@ Substitutions can be defined in the following locations: ``` code block ```" - --- ```` diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index 88558f38..5fa38b4d 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -667,7 +667,7 @@ For example: .. code-block:: rst .. csv-table:: - :file: /reuse/animals.csv + :file: /assets/animals.csv :header-rows: 1 Both markups result in the following output: @@ -987,3 +987,12 @@ More useful markup .. _substitutions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions .. _rst_epilog: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog +.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en +.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text +.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables +.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table +.. _Pygments documentation: https://pygments.org/languages/ +.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ +.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ + diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt deleted file mode 100644 index af3c3b54..00000000 --- a/docs/reuse/links.txt +++ /dev/null @@ -1,46 +0,0 @@ -.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en -.. _Canonical Reference Library: https://library.canonical.com/ -.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx -.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log -.. _csv-table reference: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table -.. _csv-table reference (MyST): https://mystmd.org/guide/directives#directive-csv-table -.. _Diátaxis: https://diataxis.fr/ -.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ -.. _Example product documentation repository: https://github.com/canonical/example-product-documentation -.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html -.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text -.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ -.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables -.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ -.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html -.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html -.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs -.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance -.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table -.. _manual import: https://readthedocs.com/dashboard/import/manual/ -.. _Markdown: https://commonmark.org/ -.. _MyST: https://myst-parser.readthedocs.io/ -.. _Open Graph: https://ogp.me/ -.. _Pa11y: https://pa11y.org/ -.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration -.. _Pygments documentation: https://pygments.org/languages/ -.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _`Sphinx`: https://www.sphinx-doc.org/ -.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html -.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/ -.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ -.. _Sphinx documentation starter pack: -.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack -.. _Sphinx documentation starter pack documentation: https://canonical-starter-pack.readthedocs-hosted.com/ -.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html -.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. _tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives -.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree -.. _Vale: https://vale.sh/ -.. _Vale rules: https://github.com/canonical/documentation-style-guide -.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ - - -.. SHORTCUTS -.. |RST| replace:: :abbr:`reST (reStructuredText)` diff --git a/docs/reuse/substitutions.txt b/docs/reuse/substitutions.txt deleted file mode 100644 index 307b5f2e..00000000 --- a/docs/reuse/substitutions.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. |version_number| replace:: 0.1.0 - -.. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - -.. |site_link| replace:: Website link -.. _site_link: https://example.com \ No newline at end of file diff --git a/docs/reuse/substitutions.yaml b/docs/reuse/substitutions.yaml deleted file mode 100644 index 0c2958d2..00000000 --- a/docs/reuse/substitutions.yaml +++ /dev/null @@ -1,4 +0,0 @@ -# Key/value substitutions to use within the Sphinx doc. -{version_number: "0.1.0", - formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} \ No newline at end of file diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst index 159e7cf6..3b5138f1 100644 --- a/docs/set-up-a-new-project.rst +++ b/docs/set-up-a-new-project.rst @@ -137,3 +137,6 @@ After that, you should see the checks running with every commit:: Run make spelling.......................................................Failed Run make linkcheck......................................................Passed Run make woke...........................................................Passed + +.. Links +.. _Diátaxis: https://diataxis.fr/ From 9c79332aa094250b2b39210771e2f8d89a25db2b Mon Sep 17 00:00:00 2001 From: nhennigan Date: Mon, 6 Apr 2026 13:44:48 -0700 Subject: [PATCH 2/6] Fix typo --- docs/set-up-a-new-project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst index 3b5138f1..eb134275 100644 --- a/docs/set-up-a-new-project.rst +++ b/docs/set-up-a-new-project.rst @@ -138,5 +138,5 @@ After that, you should see the checks running with every commit:: Run make linkcheck......................................................Passed Run make woke...........................................................Passed -.. Links +.. LINKS .. _Diátaxis: https://diataxis.fr/ From 2f733a4e6c5c8687eb36bd1cced9248b4fd52c6a Mon Sep 17 00:00:00 2001 From: nhennigan Date: Mon, 6 Apr 2026 14:31:33 -0700 Subject: [PATCH 3/6] Add missed links --- .../automatic_checks_accessibility.rst | 2 +- .../automatic_checks_inclusivelanguage.rst | 83 +++++++++++++ .../reference/automatic_checks_styleguide.rst | 116 ++++++++++++++++++ docs/reference/index.rst | 7 +- docs/reference/rst-syntax.rst | 2 + 5 files changed, 206 insertions(+), 4 deletions(-) create mode 100644 docs/reference/automatic_checks_inclusivelanguage.rst create mode 100644 docs/reference/automatic_checks_styleguide.rst diff --git a/docs/reference/automatic_checks_accessibility.rst b/docs/reference/automatic_checks_accessibility.rst index 7170edf1..d1f72564 100644 --- a/docs/reference/automatic_checks_accessibility.rst +++ b/docs/reference/automatic_checks_accessibility.rst @@ -44,4 +44,4 @@ To browse the available settings and options, see ``Pa11y``'s `README ` + +For instance:: + + This is your text. The word in question is here: :woke-ignore:`whitelist`. + +.. note:: + + 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. + +Exempt a word globally +~~~~~~~~~~~~~~~~~~~~~~ + +Vale will ignore any word listed in the ``.custom_wordlist.txt`` file. +To exempt a word, add it to this file globally. + +.. note:: + + Entries in ``.custom-wordlist`` are case-sensitive only when a capitalised word is used. 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. + +Exclude multiple lines from a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vale can be switched on and off within a file using syntax appropriate to that +format. + +To turn Vale off entirely for a section of Markdown:: + + + + This text will be ignored. + + + +.. important:: + + Only use this when other options are not suitable. + +To turn Vale off entirely for a section of |RST|:: + + .. vale off + + This text will be ignored. + + .. vale on + +.. LINKS +.. _Vale: https://vale.sh/ \ No newline at end of file diff --git a/docs/reference/automatic_checks_styleguide.rst b/docs/reference/automatic_checks_styleguide.rst new file mode 100644 index 00000000..5c2f79ea --- /dev/null +++ b/docs/reference/automatic_checks_styleguide.rst @@ -0,0 +1,116 @@ +.. _automatic-checks-styleguide: + +Style guide linting +=================== + +The starter pack includes a method to run the `Vale`_ documentation linter configured with `the Vale rules for the current style guide `_. + + +Run the style guide linting +--------------------------- + +Run the following commands from within your documentation folder. + +Check documentation with Vale:: + + make vale + +Vale can run against individual files, folders, or globs. +To set a specific target:: + + make vale TARGET=example.file + make vale TARGET=example-folder + +.. note:: + + Running Vale against a folder will also run against its subfolders. + +You can use wildcards to run against all files matching a string, or an extension. + +For example, to run against all :code:`.md` files within a folder:: + + make vale TARGET=*.md + +To match, for example, :code:`doc_1.md` and :code:`doc_2.md`:: + + make vale TARGET=doc* + + +Exempt paragraphs +----------------- + +To disable Vale linting within individual files, specific markup can be used. + +For Markdown: + +.. code-block:: Markdown + + + + This text will be ignored by Vale. + + + +For |RST|: + +.. code-block:: rest + + .. vale off + + This text will be ignored by Vale. + + .. vale on + + +Exempt directives +----------------- + +To disable Vale linting for a specific directive, you can apply a class to the section. + +For Markdown: + +.. code-block:: Markdown + + ````{class} vale-ignore + ```{code-block} + + This content will be ignored by Vale. + ``` + ```` + +.. note:: + + This should not be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. + +For |RST|: + +.. code-block:: rst + + .. class:: vale-ignore + .. code-block:: + + This content will be ignored by Vale. + +.. 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). + +Exempt words +------------ + +Use the ``:vale-ignore:`` role to ignore specific words inline, but first ensure your configuration file contains a class association in the ``rst_prolog``:: + + rst_prolog = """ + .. role:: vale-ignore + :class: vale-ignore + """ + +.. important:: + + 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 `_. + +.. LINKS +.. _Vale: https://vale.sh/ +.. _Vale rules: https://github.com/canonical/documentation-style-guide \ No newline at end of file diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d994b04c..24e3189e 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -5,7 +5,7 @@ These documents provide an overview of different features of the starter pack. Also see the following information: -- `Sphinx documentation starter pack repository`_ +- `Sphinx documentation starter pack repository `_ Contents -------- @@ -17,6 +17,7 @@ Contents default-extensions rst-syntax myst-syntax - + + .. LINKS -.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack +.. _Sphinx documentation starter pack: https://github.com/canonical/sphinx-docs-starter-pack diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index 5fa38b4d..0450e185 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -995,4 +995,6 @@ More useful markup .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html .. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ .. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ +.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree +.. _Sphinx documentation starter pack: https://github.com/canonical/sphinx-docs-starter-pack From 8247bdca299d641fe74e8f140b1461a91854cdca Mon Sep 17 00:00:00 2001 From: nhennigan Date: Mon, 6 Apr 2026 14:45:06 -0700 Subject: [PATCH 4/6] Add CHANGELOG and fix spelling typo --- CHANGELOG.md | 18 +++++++++++++++++- docs/reference/myst-syntax.md | 2 +- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ccbcfac..deacf8d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Upcoming +* Remove reuse directory * Separate default configuration for copyright and license statements. * Fix the handling of non-zero exit codes from pymarkdownlnt. * Add a how-to guide about testing the Ulwazi theme. @@ -12,12 +13,27 @@ ### Changed +* `docs/reuse/*` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/optional-customisation/interactive-tables.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/optional-customisation/mermaid-diagrams.md` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/update-starter-packs/legacy-starter-pack.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/configure-your-project.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/contributing.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/how-to/publish-on-rtd.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/automatic_checks_accessibility.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/automatic_checks_inclusivelanguage.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/automatic_checks_styleguide.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/index.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/myst-syntax.md` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reference/rst-syntax.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/index.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/set-up-a-new-project.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562) * `.github/workflows/check-removed-urls.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) * `.github/workflows/sphinx-python-dependency-build-checks.yml` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) * `docs/.gitignore` [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) * `docs/.sphinx/.wordlist.txt` [#520](https://github.com/canonical/sphinx-docs-starter-pack/pull/520) -* `docs/conf.py` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558) +* `docs/conf.py` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552), [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/Makefile` [#551](https://github.com/canonical/sphinx-docs-starter-pack/pull/551), [#552](https://github.com/canonical/sphinx-docs-starter-pack/pull/552) * `docs/redirects.txt` [#558](https://github.com/canonical/sphinx-docs-starter-pack/pull/558) * `docs/_templates/header.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549) diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md index f65e995c..5486e163 100644 --- a/docs/reference/myst-syntax.md +++ b/docs/reference/myst-syntax.md @@ -695,7 +695,7 @@ To reuse sentences or paragraphs that have little markup and special formatting, 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 limitied amount of substitutions, enter them directly into the +**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 From 2d0ed6fc73fa064f598e73617a03b8d2f8d41e57 Mon Sep 17 00:00:00 2001 From: nhennigan Date: Thu, 23 Apr 2026 11:41:20 -0700 Subject: [PATCH 5/6] Address review comments Move rst links to line as they are once off links. Updated CHANGELOG. Removed files that were deleted on main that remained after rebase. Address other minor review comments --- CHANGELOG.md | 2 +- docs/explanation/assets/components.yaml | 1 + docs/how-to/configure-your-project.rst | 25 ++-- docs/how-to/contributing.rst | 3 - docs/how-to/publish-on-rtd.rst | 15 +-- docs/how-to/run-documentation-checks.rst | 4 +- .../update-starter-packs/new-starter-pack.rst | 7 -- docs/index.rst | 5 +- .../automatic_checks_accessibility.rst | 47 ------- .../automatic_checks_inclusivelanguage.rst | 83 ------------- .../reference/automatic_checks_styleguide.rst | 116 ------------------ docs/reference/index.rst | 5 +- docs/reference/rst-syntax.rst | 41 ++----- docs/set-up-a-new-project.rst | 5 +- 14 files changed, 31 insertions(+), 328 deletions(-) delete mode 100644 docs/reference/automatic_checks_accessibility.rst delete mode 100644 docs/reference/automatic_checks_inclusivelanguage.rst delete mode 100644 docs/reference/automatic_checks_styleguide.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index deacf8d9..018fa77a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ ### Changed -* `docs/reuse/*` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) +* `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/how-to/optional-customisation/interactive-tables.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/how-to/optional-customisation/mermaid-diagrams.md` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/how-to/update-starter-packs/legacy-starter-pack.rst` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) diff --git a/docs/explanation/assets/components.yaml b/docs/explanation/assets/components.yaml index 75494524..4918b05c 100644 --- a/docs/explanation/assets/components.yaml +++ b/docs/explanation/assets/components.yaml @@ -1,3 +1,4 @@ +# This file contains the recipes for the Mermaid diagrams used in components.md documentation_architecture: - diagram_name: "Sphinx" description: "The core process of transforming source files into HTML using Sphinx." diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst index c21b5c8b..b9d99b72 100644 --- a/docs/how-to/configure-your-project.rst +++ b/docs/how-to/configure-your-project.rst @@ -12,10 +12,10 @@ While the Starter Pack provides default configuration values for most settings, 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 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. + 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. @@ -136,7 +136,7 @@ For example, you can configure whether to display Previous/Next buttons at the b 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. +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|:: @@ -157,7 +157,7 @@ Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next` 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`_. +See `Hiding Contents sidebar `_. Add your own configuration -------------------------- @@ -166,9 +166,9 @@ Custom configuration parameters for your project can be used to extend or overri The following links can help you with additional configuration: -- `Sphinx configuration`_ -- `Sphinx extensions`_ -- `Furo documentation`_ (Furo is the Sphinx theme we use as our base) +- `Sphinx configuration `_ +- `Sphinx extensions `_ +- `Furo documentation `_ (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. @@ -176,14 +176,3 @@ 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``. - -.. LINKS -.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx -.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log -.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html -.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ -.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ -.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html -.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html - - diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst index bc041d1b..cc50b4e3 100644 --- a/docs/how-to/contributing.rst +++ b/docs/how-to/contributing.rst @@ -328,6 +328,3 @@ You can (and should) run the same checks locally: make spelling make linkcheck make woke - -.. LINKS -.. _Diátaxis: https://diataxis.fr/ \ No newline at end of file diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst index 894d9e76..a34b5b0c 100644 --- a/docs/how-to/publish-on-rtd.rst +++ b/docs/how-to/publish-on-rtd.rst @@ -16,8 +16,8 @@ In general, after enabling the Starter Pack for your documentation, follow these 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. + 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``". @@ -43,7 +43,7 @@ If you don't have administrator privileges, the webhook must be set up by someon The person with administrator privileges must have connected their Read the Docs account to GitHub. See `How to connect your Read the Docs account to your Git provider`_. -See `How to manually configure a Git repository integration`_ if you want to set up the webhook manually. +See `How to manually configure a Git repository integration `_ if you want to set up the webhook manually. Make your documentation public ------------------------------ @@ -60,11 +60,4 @@ To make Read the Docs automatically build your documentation when a pull request 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. - -.. LINKS -.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html -.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html -.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs -.. _manual import: https://readthedocs.com/dashboard/import/manual/ -.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical +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 index 7515e46a..664dad0a 100644 --- a/docs/how-to/run-documentation-checks.rst +++ b/docs/how-to/run-documentation-checks.rst @@ -19,7 +19,7 @@ The starter pack comes with several tests and checks that you can (and should!) Accessibility check ------------------- -The Starter Pack checks the accessibility of the documentation with `Pa11y`_. It's configured to check for Level AA conformity to the `Web Content Accessibility Guidelines (WCAG) 2.2`_. +The 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`. @@ -46,7 +46,7 @@ The ``pa11y.json`` file in the ``.sphinx`` directory provides basic defaults exp Inclusive language check ------------------------ -The Starter Pack checks for inclusive language with a custom set of `Vale`_ rules. To check for inclusive language violations, run: +The Starter Pack checks for inclusive language with a custom set of `Vale `_ rules. To check for inclusive language violations, run: .. code-block:: bash diff --git a/docs/how-to/update-starter-packs/new-starter-pack.rst b/docs/how-to/update-starter-packs/new-starter-pack.rst index 7f1e0420..a1d52383 100644 --- a/docs/how-to/update-starter-packs/new-starter-pack.rst +++ b/docs/how-to/update-starter-packs/new-starter-pack.rst @@ -155,10 +155,3 @@ specific files or files that have been replaced with newer versions: - ``.github/workflows/sphinx-python-dependency-build-checks.yml`` - ``.github/CODEOWNERS`` - ``.github/workflows/test-starter-pack.yml`` - -- These files can be deleted as long as they are not being used in your docs: - - - ``docs/reuse/links.txt`` - - ``docs/reuse/mermaid.txt`` - - ``docs/reuse/substitutions.txt`` - - ``docs/reuse/substitutions.yaml`` diff --git a/docs/index.rst b/docs/index.rst index 64de298e..22d34f1b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ Documentation starter pack 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, +It contains common styling and configuration through the `Canonical Sphinx `_ extension, supports both |RST| and Markdown, and includes automatic documentation checks. @@ -60,6 +60,3 @@ The Canonical Sphinx starter pack is an open source project that warmly welcomes Release notes Contribute - -.. LINKS -.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx diff --git a/docs/reference/automatic_checks_accessibility.rst b/docs/reference/automatic_checks_accessibility.rst deleted file mode 100644 index d1f72564..00000000 --- a/docs/reference/automatic_checks_accessibility.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _automatic-checks-accessibility: - -Accessibility check -=================== - -The accessibility check uses `Pa11y`_ to check for accessibility issues in the documentation output. - -It is configured to use the `Web Content Accessibility Guidelines (WCAG) 2.2`_, requiring `Level AA conformance`_. - -.. note:: - - This check is only available locally. - -Install prerequisite software ------------------------------ - -``Pa11y`` must be installed through ``npm``. If you need to install ``npm``, run the following command from any location on your system:: - - sudo apt install npm - -Once ``npm`` is installed, install ``Pa11y`` by running this command from within your documentation folder. - -.. code-block:: bash - - make pa11y-install - -Run the accessibility check ---------------------------- - -Run the following command from within your documentation folder. - -Look for accessibility issues in rendered documentation:: - - make pa11y - -Configure the accessibility check ---------------------------------- - -The :file:`pa11y.json` file in the :file:`.sphinx` folder provides basic defaults. - -To browse the available settings and options, see ``Pa11y``'s `README `_ on GitHub. - -.. LINKS -.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance -.. _Pa11y: https://pa11y.org/ -.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration -.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ \ No newline at end of file diff --git a/docs/reference/automatic_checks_inclusivelanguage.rst b/docs/reference/automatic_checks_inclusivelanguage.rst deleted file mode 100644 index 108daddf..00000000 --- a/docs/reference/automatic_checks_inclusivelanguage.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _automatic-checks-inclusivelanguage: - -Inclusive language check -======================== - -The inclusive language check uses `Vale`_ to check for violations of inclusive language guidelines. - -Run the inclusive language check --------------------------------- - -Run the following command from within your documentation folder:: - - make woke - -Configure the inclusive language check --------------------------------------- - -By default, the inclusive language check is applied to Markdown and |RST| files located in the documentation folder (usually :file:`docs/`). - -Inclusive language check exemptions ------------------------------------ - -Sometimes, you might need to use some non-inclusive words. -In such cases, you may exclude them from the check. - -Exempt a word in a single instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To exempt an individual word, give the word the ``woke-ignore`` role:: - - :woke-ignore:`` - -For instance:: - - This is your text. The word in question is here: :woke-ignore:`whitelist`. - -.. note:: - - 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. - -Exempt a word globally -~~~~~~~~~~~~~~~~~~~~~~ - -Vale will ignore any word listed in the ``.custom_wordlist.txt`` file. -To exempt a word, add it to this file globally. - -.. note:: - - Entries in ``.custom-wordlist`` are case-sensitive only when a capitalised word is used. 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. - -Exclude multiple lines from a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Vale can be switched on and off within a file using syntax appropriate to that -format. - -To turn Vale off entirely for a section of Markdown:: - - - - This text will be ignored. - - - -.. important:: - - Only use this when other options are not suitable. - -To turn Vale off entirely for a section of |RST|:: - - .. vale off - - This text will be ignored. - - .. vale on - -.. LINKS -.. _Vale: https://vale.sh/ \ No newline at end of file diff --git a/docs/reference/automatic_checks_styleguide.rst b/docs/reference/automatic_checks_styleguide.rst deleted file mode 100644 index 5c2f79ea..00000000 --- a/docs/reference/automatic_checks_styleguide.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. _automatic-checks-styleguide: - -Style guide linting -=================== - -The starter pack includes a method to run the `Vale`_ documentation linter configured with `the Vale rules for the current style guide `_. - - -Run the style guide linting ---------------------------- - -Run the following commands from within your documentation folder. - -Check documentation with Vale:: - - make vale - -Vale can run against individual files, folders, or globs. -To set a specific target:: - - make vale TARGET=example.file - make vale TARGET=example-folder - -.. note:: - - Running Vale against a folder will also run against its subfolders. - -You can use wildcards to run against all files matching a string, or an extension. - -For example, to run against all :code:`.md` files within a folder:: - - make vale TARGET=*.md - -To match, for example, :code:`doc_1.md` and :code:`doc_2.md`:: - - make vale TARGET=doc* - - -Exempt paragraphs ------------------ - -To disable Vale linting within individual files, specific markup can be used. - -For Markdown: - -.. code-block:: Markdown - - - - This text will be ignored by Vale. - - - -For |RST|: - -.. code-block:: rest - - .. vale off - - This text will be ignored by Vale. - - .. vale on - - -Exempt directives ------------------ - -To disable Vale linting for a specific directive, you can apply a class to the section. - -For Markdown: - -.. code-block:: Markdown - - ````{class} vale-ignore - ```{code-block} - - This content will be ignored by Vale. - ``` - ```` - -.. note:: - - This should not be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. - -For |RST|: - -.. code-block:: rst - - .. class:: vale-ignore - .. code-block:: - - This content will be ignored by Vale. - -.. 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). - -Exempt words ------------- - -Use the ``:vale-ignore:`` role to ignore specific words inline, but first ensure your configuration file contains a class association in the ``rst_prolog``:: - - rst_prolog = """ - .. role:: vale-ignore - :class: vale-ignore - """ - -.. important:: - - 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 `_. - -.. LINKS -.. _Vale: https://vale.sh/ -.. _Vale rules: https://github.com/canonical/documentation-style-guide \ No newline at end of file diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 24e3189e..69c217f6 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -5,7 +5,7 @@ These documents provide an overview of different features of the starter pack. Also see the following information: -- `Sphinx documentation starter pack repository `_ +- `Canonical's Sphinx Starter Pack `__ Contents -------- @@ -18,6 +18,3 @@ Contents rst-syntax myst-syntax - -.. LINKS -.. _Sphinx documentation starter pack: https://github.com/canonical/sphinx-docs-starter-pack diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index 0450e185..4c30de92 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -5,15 +5,15 @@ reStructuredText syntax ======================= -The documentation files use `reStructuredText`_ (reST) 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`_. + 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`_. +For general style conventions, see the `Canonical Documentation Style Guide `_. Headings -------- @@ -94,7 +94,7 @@ 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`_. +For a list of supported languages and their respective lexers, see the official `Pygments documentation `_. .. list-table:: :header-rows: 1 @@ -309,7 +309,7 @@ Define the links in a shared file: To keep the text readable and links maintainable, put all link definitions in a file named :file:`reuse/links.txt` to include it in a custom ``rst_epilog`` directive - (see the `Sphinx documentation `_). + (see the `Sphinx documentation rst epilog `_). .. code-block:: python :caption: :spellexception:`conf.py` @@ -464,7 +464,7 @@ Navigation Every documentation page must be included as a sub-page to another page in the navigation. -This is achieved with the `toctree`_ directive in the parent page:: +This is achieved with the `toctree `_ directive in the parent page:: .. toctree:: :hidden: @@ -608,7 +608,7 @@ Both markups result in the following output: Grid tables ~~~~~~~~~~~ -See `grid tables`_ for reference. +See `grid tables `_ for reference. .. code:: @@ -625,7 +625,7 @@ See `grid tables`_ for reference. List tables ~~~~~~~~~~~ -See `list tables`_ for reference. +See `list tables `_ for reference. .. code:: @@ -742,7 +742,7 @@ Adhere to the following conventions: - Use ``PNG`` format for screenshots and ``SVG`` format for graphics. - If producing multiple output formats, use ``*`` as the file extension to have Sphinx select the best image format for the output -- See `Five golden rules for compliant alt text`_ for information about how to word the alt text. +- See `Five golden rules for compliant alt text `_ for information about how to word the alt text. Reuse ----- @@ -754,11 +754,11 @@ Substitution To reuse sentences and entire paragraphs that have little markup or special formatting, -define `substitutions`_ for them in two possible ways. +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 `_): +(see the `Sphinx documentation rst epilog `_): .. code-block:: python :caption: :spellexception:`conf.py` @@ -860,7 +860,7 @@ Adhere to the following conventions: Tabs ---- -The recommended way of creating tabs is to use the tabs that the `Sphinx design`_ extension provides. +The recommended way of creating tabs is to use the tabs that the `Sphinx design `_ extension provides. .. list-table:: :header-rows: 1 @@ -892,7 +892,7 @@ The recommended way of creating tabs is to use the tabs that the `Sphinx design` 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. +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 @@ -983,18 +983,3 @@ More useful markup - :spellexception:`PurposelyWrong` - Explicitly exempt a term from the spelling check. -.. LINKS - -.. _substitutions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions -.. _rst_epilog: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog -.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en -.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text -.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables -.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table -.. _Pygments documentation: https://pygments.org/languages/ -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ -.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree -.. _Sphinx documentation starter pack: https://github.com/canonical/sphinx-docs-starter-pack - diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst index eb134275..d8a850d2 100644 --- a/docs/set-up-a-new-project.rst +++ b/docs/set-up-a-new-project.rst @@ -64,7 +64,7 @@ Now that you've verified you can build and run the sample starter pack documenta The landing page is :file:`docs/index.rst`. Other pages are under one of the sub-directories under :file:`docs/`. The navigation menu structure is set by ``.. toctree::`` directives. These directives define the hierarchy of included content throughout the documentation. -The :file:`index.rst` page's ``toctree`` block contains the top level navigation, which by default is the `Diátaxis`_ documentation structure. +The :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: @@ -137,6 +137,3 @@ After that, you should see the checks running with every commit:: Run make spelling.......................................................Failed Run make linkcheck......................................................Passed Run make woke...........................................................Passed - -.. LINKS -.. _Diátaxis: https://diataxis.fr/ From 3315e1891f0f7bf2c0c55d6f4c7f95c1e9732727 Mon Sep 17 00:00:00 2001 From: nhennigan Date: Thu, 23 Apr 2026 11:44:16 -0700 Subject: [PATCH 6/6] Fix typo in link --- docs/reference/rst-syntax.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst index 4c30de92..097c6ee2 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -309,7 +309,7 @@ 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 `_). + (see the `Sphinx documentation rst_epilog `_). .. code-block:: python :caption: :spellexception:`conf.py` @@ -758,7 +758,7 @@ define `substitutions `_): +(see the `Sphinx documentation rst_epilog `_): .. code-block:: python :caption: :spellexception:`conf.py`