Merge pull request #1335 from scylladb/master

Sync release

.github/workflows/docs-links.yaml

@@ -19,7 +19,7 @@ jobs:
 
       - name: Link Checker
         id: lychee
-        uses: lycheeverse/lychee-action@v2.0.2
+        uses: lycheeverse/lychee-action@v2.2.0
         with:
           args: --verbose --no-progress './**/*.md' './**/*.rst'
         env:

.github/workflows/docs-pages.yaml

@@ -44,7 +44,7 @@ jobs:
             .
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v4.4.3
+        uses: actions/upload-artifact@v4.6.0
         with:
           name: github-pages
           path: ${{ runner.temp }}/artifact.tar

docs/source/commands.rst

@@ -76,14 +76,37 @@ To decrease verbosity, use the option ``-Q``:
 
         make preview SPHINXOPTS=-Q
 
-To fix the error ``pyproject.toml changed significantly since poetry.lock was last generated.``, run the following command:
+
+Troubleshooting
+...............
+
+Issue: pyproject.toml changed significantly since poetry.lock was last generated
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Solution:**
+
+#. Run the following command:
 
     .. code:: console
 
         poetry lock --no-update
 
-    Then, run the preview command again.
+#. Run the `make preview` command again.
+
+Issue: Keyring asks for a password
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This issue is due to a known problem with Poetry that primarily affects GNOME users. For more details, see `poetry/poetry#8761 <https://github.com/python-poetry/poetry/issues/8761>`_.
+
+**Solution:**
+
+#. Edit `docs/Makefile` to add the `POETRY` variable as follows:
+
+    .. code::
+
+        POETRY = PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring poetry
 
+#. Run the `make preview` command again.
 
 multiversionpreview
 ===================

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 <https://holzhaus.github.io/sphinx-multiversion/master/configuration.html>`_.
 
+Listing new versions from an external URL
+-----------------------------------------
+
+Multiversion configuration can be loaded from an external URL. 
+The following example shows how to load the multiversion configuration in the ``conf.py`` file:
+
+.. code-block:: python
+
+    # Load the multiversion configuration from an external URL
+    VERSIONS_URL = "https://<URL>/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 configuration must follow this 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 <PROJECT_NAME>. Switch to the latest stable version.
 
-
 Previewing local changes with multiversion
 ------------------------------------------
 

docs/source/configuration/template.rst

@@ -38,7 +38,6 @@ Example:
       'scylladb_scripts': 'true',
   }
 
-
 Banner options
 --------------
 
@@ -227,14 +226,19 @@ Configuration options for the left sidebar.
     - number
     - -1
     - The maximum depth of the sidebar nested entries. Set to `-1` to allow unlimited depth.
+  * - ``theme``
+    - string
+    - product
+    - The theme to use. Available values: `open-source`, `enterprise`, `cloud`, `self-hosted`, `product`.
 
 Example:
 
 .. code:: python
 
   html_theme_options = {
       'collapse_navigation': 'false',
-      'navigation_depth': '-1'
+      'navigation_depth': '-1',
+      'theme': 'product',
   }
 
 SEO options
@@ -310,3 +314,21 @@ Configuration options for enabling zendesk.
   html_theme_options = {
       'zendesk_tag': 'gq6ltsh3nfex3cnwfy4aj9',
   }
+
+
+Multiversion options
+--------------------
+
+.. list-table::
+  :widths: 20 20 20 40
+  :header-rows: 1
+
+  * - Option
+    - Type
+    - Default Value
+    - Description
+  * - ``redirect``
+    - string
+    - 
+    - Overrides the default redirection of the main domain when using multiversion. By default, it redirects to ``<DOMAIN>/stable/``. Overriding setting this can be useful if the main domain page publishes multiple documentation sets. Example: ``/manual/stable/``.
+

docs/source/examples/alerts.rst

@@ -0,0 +1,24 @@
+Alert
+=====
+
+A custom admonition to highlight important updates or announcements. It includes an icon, a short description, and an optional link that can direct users to additional information or external resources.
+
+Using:
+
+.. code-block:: rst
+
+   .. alert::
+      :link: https://scylladb.com
+      :link_text: Learn more about the change
+      :icon: logs
+
+      We’re updating our license & versioning policy.
+    
+Renders as:
+
+.. alert::
+   :link: https://scylladb.com
+   :link_text: Learn more about the change
+   :icon: logs
+
+   We’re updating our license & versioning policy.

docs/source/examples/diagrams.rst

@@ -0,0 +1,24 @@
+Diagrams 
+========
+
+The documentation toolchain supports rendering diagrams and charts using `Mermaid <https://mermaid.js.org/intro/>`_, a library designed for creating sequence diagrams, flowcharts, and other visualizations.
+
+Using:
+
+.. code-block:: python
+
+   .. mermaid ::
+
+      graph TD
+      A --> B
+      B -- Label --> C
+
+Renders:
+
+.. mermaid ::
+
+   graph TD
+   A --> B
+   B -- Label --> C
+
+For more details, refer to the `sphinxcontrib-mermaid <https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/>`_ documentation.