From cad986242745c98d1a27f7c9a7aa772de0e3d9bf Mon Sep 17 00:00:00 2001 From: David Garcia Date: Mon, 13 Jan 2025 23:18:58 +0000 Subject: [PATCH 1/3] chore: release 1.8.4 --- docs/source/upgrade/CHANGELOG.md | 15 +++++++++++++++ pyproject.toml | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/source/upgrade/CHANGELOG.md b/docs/source/upgrade/CHANGELOG.md index 86d31789c..4b2a6641c 100644 --- a/docs/source/upgrade/CHANGELOG.md +++ b/docs/source/upgrade/CHANGELOG.md @@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 1.8.4 - 14 Jan 2024 + +### Added + +- [#1277](https://github.com/scylladb/sphinx-scylladb-theme/pull/1289): Added a troubleshooting note for users encountering issues with keyring and Poetry. +- [#1302](https://github.com/scylladb/sphinx-scylladb-theme/pull/1302): Introduced Mermaid.js support for rendering diagrams from text. +- [#1303](https://github.com/scylladb/sphinx-scylladb-theme/pull/1303): Implemented a helper to fetch multiversion data from a remote URL. +- [#1314](https://github.com/scylladb/sphinx-scylladb-theme/pull/1314): Updated the user interface, including the homepage, sidebars, and breadcrumbs. +- [#1316](https://github.com/scylladb/sphinx-scylladb-theme/pull/1316): Added a license banner to announce changes to ScyllaDB’s licensing and versioning policy. +- [#1330](https://github.com/scylladb/sphinx-scylladb-theme/pull/1329): Added an option to override the multiversion redirect for the main domain, enabling redirection of `docs.scylladb.com/manual` to `docs.scylladb.com/manual/stable` instead of `docs.scylladb.com/stable`. + +### Fixed + +- [#1330](https://github.com/scylladb/sphinx-scylladb-theme/pull/1330): Resolved an issue with the alert banner position. + ## 1.8.3 - 25 Oct 2024 ### Added diff --git a/pyproject.toml b/pyproject.toml index e5b1e2649..411e110e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "sphinx-scylladb-theme" -version = "1.8.2" +version = "1.8.4" description = "A Sphinx Theme for ScyllaDB documentation projects" authors = ["David García "] exclude = [".github", "config", "docs", "extensions", ".postcss.config.js", ".prettierrc.json", "deploy.sh", "src", "package.json", "package-lock.json"] From 983cb096349a7a227ae48a35133e300f1da7234d Mon Sep 17 00:00:00 2001 From: David Garcia Date: Mon, 13 Jan 2025 23:28:48 +0000 Subject: [PATCH 2/3] docs: add fetch_multiversion_configuration guide --- docs/source/configuration/multiversion.rst | 48 +++++++++++++++++++++- docs/source/upgrade/CHANGELOG.md | 1 + 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/source/configuration/multiversion.rst b/docs/source/configuration/multiversion.rst index f1a4c0b62..bcb47eaad 100644 --- a/docs/source/configuration/multiversion.rst +++ b/docs/source/configuration/multiversion.rst @@ -39,6 +39,53 @@ For example, if you want to build docs for the tags ``3.22.0`` and ``3.21.0``, ` The extension allows configuring additional settings. To know more about them, refer to `sphinx-multiversion documentation `_. + +Listing new versions from an external URL +----------------------------------------- + +Multiversion configuration can be loaded from an external URL. +Below is an example of how to load and use the multiversion configuration: + +.. code-block:: python + + # Load the multiversion configuration from an external URL + VERSIONS_URL = "https:///versions.json" + MULTIVERSION_CONFIG = fetch_multiversion_configuration(VERSIONS_URL) + + # Builds documentation for the following tags and branches + TAGS = MULTIVERSION_CONFIG.get("tags", []) + BRANCHES = MULTIVERSION_CONFIG.get("branches", []) + + # Sets the latest version + LATEST_VERSION = MULTIVERSION_CONFIG.get("latest", "master") + + # Defines unstable versions + UNSTABLE_VERSIONS = MULTIVERSION_CONFIG.get("unstable", []) + + # Defines deprecated versions + DEPRECATED_VERSIONS = MULTIVERSION_CONFIG.get("deprecated", []) + + # Sets custom build flags + FLAGS = ["theme"] + +The JSON file used for the configuration should have the following structure: + +.. code-block:: json + + { + "tags": [], + "branches": ["master", "branch-1.8"], + "latest": "branch-1.8", + "unstable": ["master"], + "deprecated": [] + } + +- **tags:** List of Git tags to build documentation for. +- **branches:** List of Git branches to build documentation for. +- **latest:** The version considered as the latest, used as the default version. +- **unstable:** List of versions marked as unstable (e.g., under development). +- **deprecated:** List of versions marked as deprecated. + Defining a stable URL --------------------- @@ -87,7 +134,6 @@ By doing so, the warning message that appears at the top of the page will change You are viewing documentation for a deprecated version of . Switch to the latest stable version. - Previewing local changes with multiversion ------------------------------------------ diff --git a/docs/source/upgrade/CHANGELOG.md b/docs/source/upgrade/CHANGELOG.md index 4b2a6641c..a69bc31d4 100644 --- a/docs/source/upgrade/CHANGELOG.md +++ b/docs/source/upgrade/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [#1303](https://github.com/scylladb/sphinx-scylladb-theme/pull/1303): Implemented a helper to fetch multiversion data from a remote URL. - [#1314](https://github.com/scylladb/sphinx-scylladb-theme/pull/1314): Updated the user interface, including the homepage, sidebars, and breadcrumbs. - [#1316](https://github.com/scylladb/sphinx-scylladb-theme/pull/1316): Added a license banner to announce changes to ScyllaDB’s licensing and versioning policy. +- [#1316](https://github.com/scylladb/sphinx-scylladb-theme/pull/1316): Added an option to copy the anchor link when hovering over a heading. - [#1330](https://github.com/scylladb/sphinx-scylladb-theme/pull/1329): Added an option to override the multiversion redirect for the main domain, enabling redirection of `docs.scylladb.com/manual` to `docs.scylladb.com/manual/stable` instead of `docs.scylladb.com/stable`. ### Fixed From 0942b0fd0ec8e1a9529c3c878a8eaf7e1233a9f9 Mon Sep 17 00:00:00 2001 From: David Garcia Date: Mon, 13 Jan 2025 23:43:44 +0000 Subject: [PATCH 3/3] docs: update multiversion.rst --- docs/source/configuration/multiversion.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/configuration/multiversion.rst b/docs/source/configuration/multiversion.rst index bcb47eaad..c43b3627c 100644 --- a/docs/source/configuration/multiversion.rst +++ b/docs/source/configuration/multiversion.rst @@ -39,12 +39,11 @@ For example, if you want to build docs for the tags ``3.22.0`` and ``3.21.0``, ` The extension allows configuring additional settings. To know more about them, refer to `sphinx-multiversion documentation `_. - Listing new versions from an external URL ----------------------------------------- Multiversion configuration can be loaded from an external URL. -Below is an example of how to load and use the multiversion configuration: +The following example shows how to load the multiversion configuration in the ``conf.py`` file: .. code-block:: python @@ -68,7 +67,7 @@ Below is an example of how to load and use the multiversion configuration: # Sets custom build flags FLAGS = ["theme"] -The JSON file used for the configuration should have the following structure: +The JSON file used for configuration must follow this structure: .. code-block:: json @@ -86,6 +85,7 @@ The JSON file used for the configuration should have the following structure: - **unstable:** List of versions marked as unstable (e.g., under development). - **deprecated:** List of versions marked as deprecated. + Defining a stable URL ---------------------