Sync release

.github/workflows/codeql-analysis.yaml

@@ -38,11 +38,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +53,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -67,4 +67,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4

.github/workflows/docs-links.yaml

@@ -12,22 +12,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - name: Link Checker
         id: lychee
-        uses: lycheeverse/lychee-action@v2.6.1
+        uses: lycheeverse/lychee-action@v2.7.0
         with:
           args: --verbose --no-progress './**/*.md' './**/*.rst'
         env:
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
 
       - name: Create Issue From File
         if: ${{ steps.lychee.outputs.exit_code != 0 }}
-        uses: peter-evans/create-issue-from-file@v4
+        uses: peter-evans/create-issue-from-file@v6
         with:
           title: Link Checker Report
           content-filepath: ./lychee/out.md

.github/workflows/docs-pages.yaml

@@ -16,13 +16,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.10'
 
@@ -44,7 +44,7 @@ jobs:
             .
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@v5.0.0
         with:
           name: github-pages
           path: ${{ runner.temp }}/artifact.tar

.github/workflows/docs-pr.yaml

@@ -14,13 +14,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.10'
 

.github/workflows/multiversion-tests.yaml

@@ -20,13 +20,13 @@ jobs:
         working-directory: ./extensions/sphinx-multiversion
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.10'
 

.github/workflows/theme-tests.yaml

@@ -17,13 +17,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
 

docs/source/conf.py

@@ -7,6 +7,7 @@
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 
 sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("."))
 
 # -- Global variables
 
@@ -46,6 +47,7 @@
     "sphinx_scylladb_theme",
     "sphinx_multiversion",  # optional
     "myst_parser",  # optional
+    "breathe",  # optional
 ]
 
 # The suffix(es) of source filenames.
@@ -71,6 +73,23 @@
 .. |rst| replace:: restructuredText
 """
 
+# -- Options for autodoc extension ----------------------------------
+
+# Configure autodoc to show better signatures
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+add_module_names = False  # Don't prepend module names to class/function names
+
+# -- Options for breathe extension ----------------------------------
+
+breathe_projects = {
+    "SampleModule": os.path.join(
+        os.path.dirname(__file__), "examples/doxygen_output/xml"
+    )
+}
+breathe_default_project = "SampleModule"
+breathe_default_members = ("members", "undoc-members")
+
 # -- Options for myst parser ----------------------------------------
 myst_enable_extensions = ["colon_fence"]
 

docs/source/configuration/ai-chatbot.rst

@@ -7,7 +7,7 @@ ScyllaDB Docs integrates with `Biel.ai <https://biel.ai/>`_ to offer a conversat
 The chatbot can answer documentation-related questions and provide relevant links to help users find the information they need quickly.
 
 .. note::
-    This feature is in beta and disabled by default. It will be gradually enabled for all documentation sites in a future release.  
+    This feature is in beta and disabled by default. It will be gradually enabled for all documentation sites in a future release.
     If you want to enable it now, please contact us in Slack (``#scylla-docs`` channel).
 
 Installation
@@ -24,7 +24,7 @@ To enable the AI chatbot, update your ``conf.py`` file by setting ``hide_ai_chat
 Usage
 -----
 
-Once enabled, the Ask AI button will appear in the documentation interface. 
+Once enabled, the Ask AI button will appear in the documentation interface.
 Users can click the button to start a conversation, ask questions, and receive responses with relevant documentation links.
 
 .. figure:: images/ai-chatbot.png
@@ -61,4 +61,3 @@ If the chatbot does not appear:
 * Check for errors in the browser console that may indicate issues with the integration.
 
 For more details, refer to the `Biel.ai documentation <https://docs.biel.ai/>`_.
-

docs/source/configuration/page.rst

@@ -80,6 +80,17 @@ If set, hides the secondary sidebar from the page.
 
    :hide-secondary-sidebar:
 
+TOC depth
+---------
+
+Sets the depth of the table of contents in the secondary sidebar ("On This Page").
+
+Valid values are 2, 3, or 4. Default is 2.
+
+.. code-block:: none
+
+   :toc-depth: 3
+
 Hide version warning
 --------------------
 

docs/source/configuration/template.rst

@@ -226,6 +226,10 @@ Configuration options for the left sidebar.
     - number
     - -1
     - The maximum depth of the sidebar nested entries. Set to `-1` to allow unlimited depth.
+  * - ``secondary_sidebar_toc_depth``
+    - number
+    - 2
+    - The depth of the table of contents in the secondary sidebar ("On This Page"). Valid values: 2-4. Can be overridden per-page with ``:toc-depth:`` meta option.
   * - ``theme``
     - string
     - product
@@ -238,6 +242,7 @@ Example:
   html_theme_options = {
       'collapse_navigation': 'false',
       'navigation_depth': '-1',
+      'secondary_sidebar_toc_depth': 3,
       'theme': 'product',
   }
 
@@ -306,7 +311,7 @@ Configuration options for enabling zendesk.
     - Description
   * - ``zendesk_tag``
     - string
-    - 
+    -
     - Zendesk verification tag. Example: ``gq6ltsh3nfex3cnwfy4aj9``.
 
 .. code:: python
@@ -329,6 +334,5 @@ Multiversion options
     - 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/deployment/centralized-publication.rst

@@ -2,8 +2,8 @@
 Centralized publication
 =======================
 
-Certain core ScyllaDB projects are configured or published from the repository `scylladb/scylladb-docs-homepage <https://github.com/scylladb/scylladb-docs-homepage>`_ 
-instead of the project repository itself. 
+Certain core ScyllaDB projects are configured or published from the repository `scylladb/scylladb-docs-homepage <https://github.com/scylladb/scylladb-docs-homepage>`_
+instead of the project repository itself.
 
 This allows us to:
 
@@ -44,8 +44,8 @@ To add a new release to the centralized publication, submit a pull request to th
         {
             "tags": [],
             "branches": [
-                "master", 
-                "branch-2025.1", 
+                "master",
+                "branch-2025.1",
                 "branch-2025.2"
             ],
             "latest": "branch-2025.1",
@@ -63,8 +63,8 @@ To add a new release to the centralized publication, submit a pull request to th
         {
             "tags": [],
             "branches": [
-                "master", 
-                "branch-2025.1", 
+                "master",
+                "branch-2025.1",
                 "branch-2025.2"
             ],
             "latest": "branch-2025.2",
@@ -98,4 +98,3 @@ You can trigger a manual publication by following these steps:
 6. Click the green **Run workflow** button.
 
 For more details, see `Manually running a workflow <https://docs.github.com/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow>`_.
-

docs/source/examples/Doxyfile

@@ -0,0 +1,27 @@
+# Doxyfile for generating XML documentation
+
+# Project settings
+PROJECT_NAME           = "Sample Module"
+OUTPUT_DIRECTORY       = doxygen_output
+CREATE_SUBDIRS         = NO
+
+# Input settings
+INPUT                  = _sample_module.h
+FILE_PATTERNS          = *.h *.hpp *.cpp
+RECURSIVE              = NO
+
+# Output settings
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+# Extraction settings
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+
+# Other settings
+QUIET                  = YES
+WARNINGS               = NO

docs/source/examples/__init__.py

@@ -0,0 +1 @@
+"""Examples package for ScyllaDB Sphinx Theme documentation."""

docs/source/examples/_sample_module.h

@@ -0,0 +1,81 @@
+/**
+ * @file _sample_module.h
+ * @brief Sample C++ module for demonstrating Breathe/Doxygen documentation
+ *
+ * This header provides a simple database connection class to demonstrate
+ * how Breathe integrates Doxygen documentation into Sphinx.
+ */
+
+#ifndef SAMPLE_MODULE_H
+#define SAMPLE_MODULE_H
+
+#include <string>
+
+/**
+ * @brief Manages database connections
+ *
+ * This class provides methods for connecting to, querying, and disconnecting
+ * from a database.
+ */
+class DatabaseConnection {
+public:
+    /**
+     * @brief Construct a new Database Connection object
+     *
+     * @param host The database host address
+     * @param port The database port number (default: 9042)
+     * @param username Optional username for authentication
+     */
+    DatabaseConnection(const std::string& host, int port = 9042,
+                      const std::string& username = "");
+
+    /**
+     * @brief Establish a connection to the database
+     *
+     * @return true if connection was successful
+     * @return false if connection failed
+     * @throws ConnectionError if connection fails after retries
+     */
+    bool connect();
+
+    /**
+     * @brief Execute a query on the database
+     *
+     * @param query The SQL query string to execute
+     * @return Query results as a string
+     * @throws RuntimeError if not connected to database
+     */
+    std::string execute(const std::string& query);
+
+    /**
+     * @brief Close the database connection
+     */
+    void disconnect();
+
+private:
+    std::string host_;      ///< Database host address
+    int port_;              ///< Database port number
+    std::string username_;  ///< Optional username
+    bool connected_;        ///< Connection status
+};
+
+/**
+ * @brief Format a SQL query string
+ *
+ * @param query The SQL query template
+ * @param indent Number of spaces for indentation (default: 4)
+ * @return Formatted SQL query string
+ */
+std::string format_query(const std::string& query, int indent = 4);
+
+/**
+ * @brief Validate database connection parameters
+ *
+ * @param host The database host
+ * @param port The database port
+ * @return true if parameters are valid
+ * @return false otherwise
+ */
+bool validate_connection_params(const std::string& host, int port);
+
+#endif // SAMPLE_MODULE_H