Backport changes to 1.8 branch

.github/workflows/docs-links.yaml

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

.github/workflows/docs-pages.yaml

@@ -44,7 +44,7 @@ jobs:
             .
 
       - name: Upload artifact
-        uses: actions/[email protected].0
+        uses: actions/[email protected].3
         with:
           name: github-pages
           path: ${{ runner.temp }}/artifact.tar

.github/workflows/multiversion-tests.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.7
+          python-version: '3.10'
 
       - name: Set up requirements
         run: python -m pip install -r requirements.txt

.github/workflows/theme-tests.yaml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.7
+          python-version: "3.10"
 
       - name: Set up env
         run: |

docs/Makefile

@@ -24,6 +24,9 @@ setupenv:
 .PHONY: setup
 setup:
 	$(POETRY) install
+
+.PHONY: update
+update:
 	$(POETRY) update
 
 # Clean commands

docs/_utils/pyproject_template.toml

@@ -7,7 +7,7 @@ authors = ["ScyllaDB Documentation Contributors"]
 [tool.poetry.dependencies]
 python = "^3.10"
 pygments = "^2.18.0"
-sphinx-scylladb-theme = "^1.6.1"
+sphinx-scylladb-theme = "^1.8.1"
 myst-parser = "^3.0.1"
 sphinx-autobuild = "^2024.4.19"
 Sphinx = "^7.3.7"

docs/source/commands.rst

@@ -4,23 +4,52 @@ Commands
 
 Use the command-line interface to run the following commands.
 
-Prerequisites
--------------
+.. note:: Make sure you meet the necessary prerequisites before running these commands. For details, see :ref:`Prerequisites <prerequisites>`.
+
+Setup commands
+--------------
+
+setupenv
+========
+
+Installs system dependencies required to build the docs, such as Poetry.
+
+.. code:: console
+
+    make setupenv
+
+setup
+=====
+
+Installs the required Python dependencies to build the documentation.
+
+.. code:: console
+
+    make setup
+
+.. note:: ``make setup`` is called automatically before running build commands.
 
-To run the following commands, you will need to have installed:
+update
+======
+
+Updates Python dependencies to the latest version.
+
+.. code:: console
 
-- A Unix-based terminal. For Windows, use `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`_.
-- `Python 3.7 <https://www.python.org/downloads/>`_ or later.
-- `Poetry #.12 <https://python-poetry.org/docs/master/>`_ or later.
-- `Make <https://www.gnu.org/software/make/>`_.
-- `Git <https://git-scm.com/>`_.
+    make update
+
+As a result, updates the ``poetry.lock`` file.
+
+
+Build commands
+--------------
 
 .. _Make_Preview:
 
-Preview current branch
-----------------------
+preview
+=======
 
-The preview command builds a local instance of the docs site so you can view the rendering in a sandbox environment on your local browser.
+Builds a local instance of the docs site so you can view the rendering in a sandbox environment on your local browser.
 
 To preview the docs:
 
@@ -47,18 +76,19 @@ 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:
+To fix the error ``pyproject.toml changed significantly since poetry.lock was last generated.``, run the following command:
 
     .. code:: console
 
         poetry lock --no-update
 
     Then, run the preview command again.
 
-Preview multiversion
---------------------
 
-The multiversionpreview command generates a local instance of the docs site with all :doc:`specified versions <../configuration/multiversion>` available for navigation.
+multiversionpreview
+===================
+
+Generates a local instance of the docs site with all :doc:`specified versions <../configuration/multiversion>` available for navigation.
 You can view the rendering in a sandbox environment on your local browser.
 
 To preview multiple versions:
@@ -72,10 +102,26 @@ To preview multiple versions:
 
 #. Open http://0.0.0.0:5500/ with your preferred browser.
 
-For further guidance on using the `multiversionpreview command`, see :doc:`Multiversion configuration <../configuration/multiversion>`.
+For further guidance on using the ``multiversionpreview command``, see :doc:`Multiversion configuration <../configuration/multiversion>`.
+
+dirhtml
+=======
 
-Build HTML for multiple versions
---------------------------------
+Generates the documentation in HTML format.
+
+.. note:: The command ``make dirhtml`` is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run ``make dirhtml``, but ``make preview`` instead.
+
+.. code:: console
+
+    cd docs
+    make multiversion
+
+Docs are generated under the ``docs/_build/dirhtml`` directory.
+
+multiversion
+============
+
+Generates multiple versions of the docs with all :doc:`specified versions <../configuration/multiversion>` available for navigation.
 
 .. note:: The command ``make multiversion`` is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run ``make multiversion``, but ``make preview`` instead.
 
@@ -84,22 +130,43 @@ Build HTML for multiple versions
     cd docs
     make multiversion
 
-The previous command generates HTML docs under the ``docs/_build/dirhtml`` directory.
+Docs are generated under the ``docs/_build/dirhtml`` directory.
 
-Clean all builds
-----------------
+redirects
+=========
 
-The ``make preview`` operation creates content in the ``_build`` directory. When making changes to the docs, it is helpful to delete the contents of this directory before running ``make preview``.
+Generates HTML redirects from the ``_utils/redirects.yaml`` file.
+
+.. note:: The command ``make multiversion`` is aimed to be used by GitHub Actions CI.
+
+.. code:: console
+
+    cd docs
+    make multiversion
+
+Redirects are generated under the ``docs/_build/dirhtml`` directory.
+
+Clean commands
+--------------
+
+clean
+=====
+
+Before making changes to the docs, it's helpful to clear the previous build by deleting the contents of the ``build`` directory.
+This ensures that the changes you make are reflected correctly.
 
 .. code:: console
 
     cd docs
     make clean
 
-Check for broken links
-----------------------
+Test commands
+-------------
+
+linkcheck
+=========
 
-Check for broken links on the documentation site.
+Checks the documentation site for broken links.
 
 .. code:: console
 

docs/source/conf.py

@@ -13,6 +13,7 @@
 # Builds documentation for the following tags and branches.
 TAGS = []
 BRANCHES = [
+    "branch-1.8",
     "branch-1.7",
     "branch-1.6",
     "branch-1.5",
@@ -24,7 +25,7 @@
     "master",
 ]
 # Sets the latest version.
-LATEST_VERSION = "branch-1.7"
+LATEST_VERSION = "branch-1.8"
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = ["master"]
 # Set which versions are deprecated

docs/source/examples/glossary.rst

@@ -18,6 +18,12 @@ The glossary has the following format:
       Term 2
          Definition
 
+      Long description
+         Lorem ipsum dolor sit amet, ``consectetur`` adipiscing elit. Ut tincidunt orci non pellentesque hendrerit. Sed vitae sem convallis, porta felis ut, varius libero. Suspendisse eget auctor felis. Sed sit amet sapien posuere, eleifend urna ut, interdum nisi.
+         Donec porta nibh leo, vitae convallis risus ornare sit amet. Mauris porttitor ipsum in mi dignissim, vel volutpat massa placerat.
+
+         Vivamus et cursus turpis, id luctus lectus.
+
 This will result in:
 
 .. glossary::
@@ -29,7 +35,10 @@ This will result in:
       Definition
 
    Long description
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec sed lorem quis dui mattis suscipit sit amet id dui. Suspendisse elementum rutrum vulputate. Cras in velit sapien. Etiam egestas turpis eget arcu feugiat semper. Ut blandit sagittis cursus. Maecenas at varius ex, et porttitor mi. Nullam tortor elit, tincidunt et nulla id, porta vestibulum nibh. Quisque tellus elit, maximus at congue quis, molestie eget urna. Donec odio lorem, semper sed pharetra eu, sodales eget velit. Donec dignissim quam mi, nec vehicula magna gravida in. Vestibulum consectetur, sem a tristique porta, risus est laoreet nibh, sed cursus nibh est vel massa. Vestibulum aliquet varius tellus eu pulvinar. Integer a lorem sollicitudin, placerat orci eu, lobortis velit. Pellentesque sit amet magna porta augue iaculis egestas dapibus sed dui.
+      Lorem ipsum dolor sit amet, ``consectetur`` adipiscing elit. Ut tincidunt orci non pellentesque hendrerit. Sed vitae sem convallis, porta felis ut, varius libero. Suspendisse eget auctor felis. Sed sit amet sapien posuere, eleifend urna ut, interdum nisi.
+      Donec porta nibh leo, vitae convallis risus ornare sit amet. Mauris porttitor ipsum in mi dignissim, vel volutpat massa placerat.
+
+      Vivamus et cursus turpis, id luctus lectus.
 
 
 

docs/source/examples/hero-box.rst

@@ -47,7 +47,7 @@ The ``hero-box`` directive supports the following options:
   * - ``button_icon``
     - string
     -
-    - fa fa-home
+    - icon-home
     - A list of CSS classes to render an icon, separated by comma or space.
   * - ``button_icon_position``
     - string

docs/source/examples/panel-box.rst

@@ -48,13 +48,48 @@ For example, using:
 .. code-block:: rst
 
    .. panel-box::
-      :title: Admin
+      :title: Title
 
-      Test
+      Body
 
 Results in:
 
 .. panel-box::
-    :title: Admin
+    :title: Title
 
-    Test
+    Body
+
+Compatibility with previous versions
+------------------------------------
+
+Some panel boxes in the open-source project where defined with raw html as follows:
+
+.. code-block:: rst
+
+  .. raw:: html
+
+    <div class="panel callout radius animated">
+        <div class="row">
+          <div class="medium-3 columns">
+            <h5 id="getting-started">Title</h5>
+          </div>
+          <div class="medium-9 columns">
+            Body
+          </div>
+        </div>
+    </div>
+
+This example tests how the previous panel box is rendered:
+
+.. raw:: html
+
+  <div class="panel callout radius animated">
+      <div class="row">
+        <div class="medium-3 columns">
+          <h5 id="getting-started">Title</h5>
+        </div>
+        <div class="medium-9 columns">
+          Body
+        </div>
+      </div>
+  </div>

docs/source/examples/toc.rst

@@ -3,6 +3,10 @@ TOC
 
 These directives create TOCs automatically
 
+.. contents::
+   :depth: 2
+   :local:
+
 TOC
 ---
 

docs/source/examples/tooltips.rst

@@ -15,32 +15,38 @@ Syntax
 Usage
 -----
 
-Tooltip with text
-.................
+Tooltip with inline text
+........................
 
 Using:
 
 .. code-block:: rst
 
    Here is a :include_tooltip:`word <This is the tooltip text>`.
+
+   Here is another :include_tooltip:`term with long description <Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tincidunt orci non pellentesque hendrerit. Sed vitae sem convallis, porta felis ut, varius libero. Suspendisse eget auctor felis. Sed sit amet sapien posuere, eleifend urna ut, interdum nisi.>`.
 
 Results in:
 
 Here is a :include_tooltip:`word <This is the tooltip text>`.
 
+Here is another :include_tooltip:`term with long description <Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tincidunt orci non pellentesque hendrerit. Sed vitae sem convallis, porta felis ut, varius libero. Suspendisse eget auctor felis. Sed sit amet sapien posuere, eleifend urna ut, interdum nisi.>`.
+
 Tooltip from a glossary entry
 .............................
 
+You can also create a tooltip by referencing a glossary term. The tooltip will automatically pull the term's definition from the glossary.
+
 Using:
 
 .. code-block:: rst
 
    Here is a :include_tooltip:`term <Term 1>`.
-
-This will load the definition of `term-name` from your project's glossary and use it as the tooltip text for "term".
-
+
+   Here is another :include_tooltip:`term loading a long description <Long description>` from the glossary.
 
 Results in:
 
-Here is a :include_tooltip:`term <Term 1>`.
+Here is a :include_tooltip:`term <Term 1>` loading the description from the glossary.
 
+Here is another :include_tooltip:`term loading a long description <Long description>` from the glossary.