chore: 1.3.1 release prep

.github/workflows/automatic-doc-checks.yml

@@ -8,10 +8,10 @@ on:
     paths:
       - 'docs/**'   # Only run on changes to the docs directory
 
+  workflow_call:
   workflow_dispatch:
     # Manual trigger
 
-
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/check-removed-urls.yml

@@ -1,6 +1,7 @@
 name: Check for removed URLs
 
 on:
+  workflow_call:
   pull_request:
     branches: [main]
 

.github/workflows/markdown-style-checks.yml

@@ -1,6 +1,7 @@
 name: Markdown style checks
 
 on:
+  workflow_call:
   push:
     branches:
     - main

.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -15,6 +15,7 @@ on:
   push:
     branches: [ main ]
   pull_request:
+  workflow_call:
   workflow_dispatch: # manual trigger
 
 concurrency:

CHANGELOG.md

@@ -1,5 +1,19 @@
 # sphinx-docs-starter-pack changelog
 
+## 1.3.1
+
+* Switches doc links to `stable` slug.
+* !!POTENTIAL CONFIGURATION ISSUE: Fixes duplicate version strings in sitemaps for versioned docs. This removes the `version` variable previously set in the sitemaps configuration section of `conf.py`. If you have any custom code that uses this variable elsewhere, do not remove it.
+
+### Changed
+
+* `docs/conf.py` [#477](https://github.com/canonical/sphinx-docs-starter-pack/pull/477)
+* `docs/Makefile` [#468](https://github.com/canonical/sphinx-docs-starter-pack/pull/468), [#472](https://github.com/canonical/sphinx-docs-starter-pack/pull/472)
+* `.github/workflows/automatic-doc-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
+* `.github/workflows/check-removed-urls.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
+* `.github/workflows/markdown-style-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
+* `.github/workflows/sphinx-python-dependency-build-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
+
 ## 1.3.0
 
 * !!!BREAKING: Updated deps to use atomic extensions, not `canonical-sphinx[full]`. Updated `sphinx-terminal` uses backwards incompatible syntax

docs/.sphinx/version

@@ -1 +1 @@
-1.3.0
+1.3.1

docs/Makefile

@@ -7,9 +7,9 @@
 SPHINXDIR       = .sphinx
 SPHINXOPTS      ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
 SPHINXBUILD     ?= $(VENVDIR)/bin/sphinx-build
-SOURCEDIR       = .
+SOURCEDIR       ?= .
 BUILDDIR        = _build
-VENVDIR         = $(SPHINXDIR)/venv
+VENVDIR         ?= $(SPHINXDIR)/venv
 PA11Y           = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
 VENV            = $(VENVDIR)/bin/activate
 TARGET          = *
@@ -44,9 +44,9 @@ help:
 	@echo "-------------------------------------------------------------"
 	@echo
 
-.PHONY: help full‑help html epub pdf linkcheck spelling spellcheck woke \
-        vale pa11y run serve install pa11y‑install   \
-        vale‑install pdf‑prep pdf‑prep‑force clean clean‑doc allmetrics \
+.PHONY: help full-help html epub pdf linkcheck spelling spellcheck woke \
+        vale pa11y run serve install pa11y-install   \
+        vale-install pdf-prep pdf-prep-force clean clean-doc allmetrics \
         update lint-md
 
 full-help: $(VENVDIR)

docs/conf.py

@@ -186,14 +186,9 @@
 
 html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 
-# URL scheme. Add language and version scheme elements.
-# When configured with RTD variables, check for RTD environment so manual runs succeed:
-
-if 'READTHEDOCS_VERSION' in os.environ:
-    version = os.environ["READTHEDOCS_VERSION"]
-    sitemap_url_scheme = '{version}{link}'
-else:
-    sitemap_url_scheme = 'MANUAL/{link}'
+# sphinx-sitemap uses html_baseurl to generate the full URL for each page:
+
+sitemap_url_scheme = '{link}'
 
 # Include `lastmod` dates in the sitemap:
 

docs/how-to/contributing-myst.md

@@ -201,9 +201,9 @@ TODO: test command 2
 
 ## Documentation
 
-ACME's documentation is stored in the `DOCDIR` directory of the repository. It is based on the [Canonical starter pack](https://canonical-starter-pack.readthedocs-hosted.com/) and hosted on [Read the Docs](https://about.readthedocs.com/).
+ACME's documentation is stored in the `DOCDIR` directory of the repository. It is based on the [Canonical starter pack](https://canonical-starter-pack.readthedocs-hosted.com/stable/) and hosted on [Read the Docs](https://about.readthedocs.com/).
 
-For general guidance, refer to the [starter pack guide](https://canonical-starter-pack.readthedocs-hosted.com/).
+For general guidance, refer to the [starter pack guide](https://canonical-starter-pack.readthedocs-hosted.com/stable/).
 
 For syntax help and guidelines, refer to the syntax guides contained in the [rST](project:#style-guide) and [MyST](project:#myst_style_guide) syntax guides.
 

docs/how-to/contributing.rst

@@ -295,7 +295,7 @@ Documentation
 
 ACME's documentation is stored in the ``DOCDIR`` directory of the repository.
 It is based on the `Canonical starter pack
-<https://canonical-starter-pack.readthedocs-hosted.com/>`_
+<https://canonical-starter-pack.readthedocs-hosted.com/stable/>`_
 and hosted on `Read the Docs <https://about.readthedocs.com/>`_.
 
 For syntax help and guidelines,

docs/how-to/index.rst

@@ -18,7 +18,6 @@ Set up, configure, upgrade, and customize your project to keep it organized and
    customise-pdf
    migrate-from-pre-extension
    update
-   contributing
    troubleshoot-issues
 
 Optional features and workflows

docs/how-to/set-up-sitemaps.rst

@@ -31,55 +31,26 @@ Add ``sphinx_sitemap`` to ``extensions`` in your configuration file (:file:`docs
 
     extensions = ['sphinx_sitemap']
 
-Required sitemap configuration
-------------------------------
-
-Sphinx Sitemap requires a ``html_baseurl`` configured for the project in your
-configuration file. For example, in :file:`docs/conf.py`:
-
-.. code-block::
-
-    html_baseurl = 'https://canonical-starter-pack.readthedocs-hosted.com/'
-
-Make sure to include the trailing slash (``/``) to avoid errors in the concatenated
-URLs in the sitemap.
-
-.. note::
-
-    Sitemap configuration is included in the Starter pack's
-    `default configuration file <https://github.com/canonical/sphinx-docs-starter-pack/blob/a489ae041f6cebb7948fdf21b996e8c67d636a83/docs/conf.py#L176>`_.
-
-URL configuration
------------------
-
-Sphinx sitemap uses a configurable URL scheme to set language and version options
-for your documentation. If you have no languages and no versions in your URL, add
-the following to your ``conf.py`` file:
-
-.. code-block::
-
-    sitemap_url_scheme = "{link}"
+Sitemap configuration
+---------------------
 
-To add versioning, this can be done manually, or you can read the version from
-the RTD instance. To implement a manual version:
+The Sphinx starter pack's configuration file (:file:`docs/conf.py`) includes default sitemap configuration.
 
-.. code-block::
+The ``sphinx-sitemap`` extension requires a ``html_baseurl`` variable to be configured.
+This is set as follows:
 
-    sitemap_url_scheme = "<version>/{link}"
+.. code-block:: python
 
-Or, if the version is set with the ``version`` key in your configuration file:
+    html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 
-.. code-block::
+When building on Read the Docs, this sets ``html_baseurl`` dynamically to the value of the
+``READTHEDOCS_CANONICAL_URL`` environment variable, which resolves to the full URL of the documentation
+including the version and language (if applicable).
 
-    sitemap_url_scheme = "{version}{link}"
+In local builds and builds on other hosts, ``html_baseurl`` defaults to ``/``.
 
-To read from the provided RTD environment variable::
-
-    if 'READTHEDOCS_VERSION' in os.environ:
-        version = os.environ["READTHEDOCS_VERSION"]
-        sitemap_url_scheme = '{version}{link}'
-    else:
-        sitemap_url_scheme = 'MANUAL/{link}'
+The ``sitemap_url_scheme`` variable is set to ``'{link}'`` by default. This uses the value of ``html_baseurl`` to generate
+the full URL for each page for the sitemap.
 
 .. note::
 
@@ -160,7 +131,7 @@ For instance, using the starter pack as an example, with three versions
 
             Disallow: # Allow everything
 
-            Sitemap: https://canonical-starter-pack.readthedocs-hosted.com/latest/sitemapindex.xml
+            Sitemap: https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemapindex.xml
 
 3.  Create a ``sitemapindex.xml`` file, in the same directory as your configuration
     file, which points to the sitemap files of each of your documentation sets:
@@ -169,7 +140,7 @@ For instance, using the starter pack as an example, with three versions
 
             <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
             <sitemap>
-            <loc>https://canonical-starter-pack.readthedocs-hosted.com/latest/sitemap.xml</loc>
+            <loc>https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemap.xml</loc>
             </sitemap>
             <sitemap>
             <loc>https://canonical-starter-pack.readthedocs-hosted.com/3.0/sitemap.xml</loc>

docs/tutorial/set-up.rst

@@ -35,8 +35,9 @@ Remove the files that can't be reused:
 
 Review and remove the GitHub workflows in ``.github/workflows/`` that your project might not need:
 
-- :file:`sphinx-python-dependency-build-checks.yml` verifies Python dependencies for the documentation system. If your project has its own dependency checks, it won't need this workflow.
-- :file:`markdown-style-checks.yml` runs the built-in Markdown linter. If your project already validates its Markdown files, it won't need this workflow.
+- :file:`cla-check.yml` verifies whether contributors have signed the `Canonical License Agreement <https://canonical.com/legal/contributors>`_. All Canonical projects require this check, so if you're adding docs to an existing Canonical project that already has it, remove this workflow.
+- :file:`sphinx-python-dependency-build-checks.yml` verifies Python dependencies for the documentation system. If your project has its own dependency checks, remove this workflow.
+- :file:`markdown-style-checks.yml` runs the built-in Markdown linter. If your project already validates its Markdown files, remove this workflow.
 
 
 Build and run the local server