diff --git a/CHANGELOG.md b/CHANGELOG.md index 56ad4d97..8dcb1d5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Upcoming +* Remove reuse directory * Rename `.sphinx/` directory to `_dev/`. * Separate default configuration for copyright and license statements. * Fix the handling of non-zero exit codes from pymarkdownlnt. @@ -14,21 +15,14 @@ ### Changed -* `docs/how-to/run-documentation-checks.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/build-and-preview.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/update-starter-packs/new-starter-pack.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/update-starter-packs/legacy-starter-pack.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/update-starter-packs/index.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/optional-customisation/external-referencing-intersphinx.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/optional-customisation/enable-google-analytics.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) -* `docs/how-to/optional-customisation/customise-pdf.rst` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) +* `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576) * `docs/.sphinx/` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) * `docs/conf.py` [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) * `.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), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) * `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), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598) * `docs/_templates/header.html` [#549](https://github.com/canonical/sphinx-docs-starter-pack/pull/549) diff --git a/docs/conf.py b/docs/conf.py index 468f01f5..87a5d440 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..4918b05c 100644 --- a/docs/reuse/components.yaml +++ b/docs/explanation/assets/components.yaml @@ -1,3 +1,4 @@ +# This file contains the recipes for the Mermaid diagrams used in components.md documentation_architecture: - diagram_name: "Sphinx" description: "The core process of transforming source files into HTML using Sphinx." @@ -6,7 +7,7 @@ documentation_architecture: A["Source Files
(.rst or .md)"] -->|provides content to| C[Sphinx] B["Configuration
(docs/conf.py)"] -->|provides settings to| C C -->|generates| D[Built HTML Pages] - rendered_image: "../explanation/assets/sphinx.png" + rendered_image: "sphinx.png" - diagram_name: "Python environment" description: "The relationship between the host system and the virtual environment." @@ -23,7 +24,7 @@ documentation_architecture: end Sphinx -->|builds| HTML[HTML] end - rendered_image: "../explanation/assets/python-starter-pack.png" + rendered_image: "python-starter-pack.png" - diagram_name: "Extensions" description: "How built-in and third-party extensions are integrated and activated via requirements and conf.py." @@ -38,7 +39,7 @@ documentation_architecture: end BuiltIn -->|are activated in| Conf[/"Project configuration file (docs/conf.py)"\] ThirdParty -->|are activated in| Conf - rendered_image: "../explanation/assets/extensions.png" + rendered_image: "extensions.png" - diagram_name: "Read the Docs" description: "Details the declaration of build logic in the RTD configuration file for hosting." @@ -49,7 +50,7 @@ documentation_architecture: Python_Ver["Python version"] -->|is declared in| RTD_Conf RTD_Conf -->|defines the build logic for| RTD["Read the Docs (RTD)"] RTD -->|builds and hosts| HTML[/"HTML"\] - rendered_image: "../explanation/assets/rtd-build.png" + rendered_image: "rtd-build.png" - diagram_name: "Third-party extensions" description: "Focuses on the specific installation path for external dependencies via pip and requirements." @@ -64,4 +65,4 @@ documentation_architecture: end Python -->|installs the contents of| Reqs Reqs -->|specifies| ThirdParty - rendered_image: "../explanation/assets/third-party-extensions.png" \ No newline at end of file + rendered_image: "third-party-extensions.png" \ No newline at end of file diff --git a/docs/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..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,4 +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``. - 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..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,4 +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. +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 c1b4955a..410d7f41 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 ``_dev`` directory provides basic defaults expect 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/legacy-starter-pack.rst b/docs/how-to/update-starter-packs/legacy-starter-pack.rst index 66a60769..19a91813 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/how-to/update-starter-packs/new-starter-pack.rst b/docs/how-to/update-starter-packs/new-starter-pack.rst index a05825a1..f011f375 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 36a97373..e734e208 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ Sphinx Starter Pack documentation The documentation Starter Pack helps you to quickly set up, build, and publish documentation with Sphinx. -It contains common styling and configuration through the `Canonical Sphinx`_ extension, +It contains common styling and configuration through the `Canonical Sphinx `_ extension, supports both |RST| and Markdown, and includes automatic documentation checks. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 99a0f4b3..9cc1f3a5 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,7 +6,7 @@ for the Starter Pack's GitHub workflows. Also see the following information: -- `Sphinx documentation Starter Pack repository`_ +- `Canonical's Sphinx Starter Pack `__ Contents -------- @@ -18,4 +18,4 @@ Contents default-extensions rst-syntax myst-syntax - + diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md index 024a74b9..cbd63bc8 100644 --- a/docs/reference/myst-syntax.md +++ b/docs/reference/myst-syntax.md @@ -697,7 +697,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 limited amount of substitutions, enter them directly into the +`myst_substitutions` variable in `conf.py`: ```{code-block} python :caption: "{spellexception}`conf.py`" @@ -710,6 +711,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 @@ -719,7 +726,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: ```` --- @@ -732,7 +741,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 caf801e8..67ff1d14 100644 --- a/docs/reference/rst-syntax.rst +++ b/docs/reference/rst-syntax.rst @@ -8,15 +8,15 @@ reStructuredText syntax ======================= -The Starter Pack supports `reStructuredText`_ (reST). +The documentation files use `reStructuredText `_ (reST) syntax. See the following sections for syntax help and conventions. .. note:: - This guide assumes that you are using the `Sphinx documentation starter pack`_. - Some of the mentioned syntax requires Sphinx extensions (which are enabled in the Starter Pack). + 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 -------- @@ -97,7 +97,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 @@ -312,7 +312,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` @@ -467,7 +467,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: @@ -611,7 +611,7 @@ Both markups result in the following output: Grid tables ~~~~~~~~~~~ -See `grid tables`_ for reference. +See `grid tables `_ for reference. .. code:: @@ -628,7 +628,7 @@ See `grid tables`_ for reference. List tables ~~~~~~~~~~~ -See `list tables`_ for reference. +See `list tables `_ for reference. .. code:: @@ -670,7 +670,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: @@ -745,7 +745,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 ----- @@ -757,11 +757,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` @@ -863,7 +863,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 @@ -895,7 +895,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 @@ -986,7 +986,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 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 6503dc86..de8a5ad5 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: