Remove reuse directory

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)

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.

docs/reuse/components.yaml → 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<br/>(.rst or .md)"] -->|provides content to| C[Sphinx]
           B["Configuration<br/>(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"
+    rendered_image: "third-party-extensions.png"

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 <https://github.com/canonical/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 <https://github.com/canonical/sphinx-docs-starter-pack/wiki/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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`_ 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 <Furo documentation_>`_), which can be used to hide the page-internal table of content.
-See `Hiding Contents sidebar`_.
+See `Hiding Contents sidebar <https://pradyunsg.me/furo/customisation/toc/>`_.
 
 Add your own configuration
 --------------------------
@@ -166,14 +166,13 @@ 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 <https://www.sphinx-doc.org/en/master/usage/configuration.html>`_
+- `Sphinx extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+- `Furo documentation <https://pradyunsg.me/furo/quickstart/>`_ (Furo is the Sphinx theme we use as our base)
 
 If you need additional Python packages for any custom processing you do in your documentation, add them to the :file:`docs/requirements.txt` file.
 
 Disable failure on warning
 --------------------------
 
 The docs build (``make html``) is, by default, set to fail when a warning (``WARNING`` in the build log) is encountered. To disable this setting, remove the ``--failure-on-warning`` option from the command specified in the ``html`` target in the ``Makefile``.
-

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/

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
 ```

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 <build-clean>`.
 #. 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 <https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html>`_.
+#. Use the `manual import <https://readthedocs.com/dashboard/import/manual/>`_ 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 <https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html>`_ 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.

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 <https://pa11y.org/>`_. It's configured to check for Level AA conformity to the `Web Content Accessibility Guidelines (WCAG) 2.2 <https://www.w3.org/TR/WCAG22/>`_.
 
 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 <https://vale.sh/>`_ rules. To check for inclusive language violations, run:
 
 .. code-block:: bash
 

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

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``

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 <https://github.com/canonical/canonical-sphinx>`_ extension,
 supports both |RST| and Markdown, and includes automatic documentation checks.
 
 

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 <https://github.com/canonical/sphinx-docs-starter-pack>`__
 
 Contents
 --------
@@ -18,4 +18,4 @@ Contents
    default-extensions
    rst-syntax
    myst-syntax
-   
+

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
                          ```"
-
   ---
   ````