diff --git a/CHANGELOG.md b/CHANGELOG.md index 90388290..03972a3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,11 @@ ## 1.4.0 * Switches doc links to `stable` slug. +* !!POTENTIAL BREAKING CHANGE: 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) diff --git a/docs/conf.py b/docs/conf.py index 9a54d8b2..1b2a20ca 100644 --- a/docs/conf.py +++ b/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: diff --git a/docs/how-to/set-up-sitemaps.rst b/docs/how-to/set-up-sitemaps.rst index a3d04b1e..84c97cd4 100644 --- a/docs/how-to/set-up-sitemaps.rst +++ b/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 `_. - -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 = "/{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::