Enable multiversion

.github/workflows/pages.yml

@@ -3,9 +3,13 @@ name: "CI Docs"
 on:
   push:
     branches:
-    - latest
+    - scylla-3.x
     paths:
     - 'docs/**'
+    - 'faq/**'
+    - 'manual/**'
+    - 'changelog/**'
+    - 'upgrade_guide/**'
 jobs:
   release:
     name: Build

README-dev.rst

@@ -33,3 +33,36 @@ Build Sphinx docs for all the versions defined in ``docs/conf.py``.
 Then, open ``docs/_build/dirhtml/<version>/index.html`` with your preferred browser.
 
 **NOTE:** If you only can see docs generated for the master branch, try to run ``git fetch --tags`` to download the latest tags from remote.
+
+Defining supported versions
+===========================
+
+Let's say you want to generate docs for the new version ``scylla-3.x.y``.
+
+1. The file ``.github/workflows`` defines the branch from where all the documentation versions will be build.
+
+.. code:: yaml
+
+    on:
+    push:
+        branches:
+        - scylla-3.x
+
+In our case, this branch currently is``scylla-3.x``.
+In practice, this means that the file ``docs/source/conf.py`` of ```scylla-3.x`` defines which documentation versions are supported.
+
+2. In the file ``docs/source/conf.py`` (``scylla-3.x`` branch), list the new target version support inside the ``BRANCHES`` array.
+For example, listing ``scylla-3.x.y`` should look like in your code:
+
+.. code:: python
+
+    BRANCHES = ['scylla-3.x.y']
+    smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
+
+3. (optional) If the new version is the latest stable version, update as well the variable ``smv_latest_version`` in ``docs/source/conf.py``.
+
+.. code:: python
+
+    smv_latest_version = 'scylla-3.x.y'
+
+4. Commit & push the changes to the ``scylla-3.x`` branch.

changelog/README.md

@@ -5,36 +5,36 @@
   3.x versions get published.
 -->
 
-## 3.11.0 (in progress)
+### 3.11.0 (in progress)
 
 - [improvement] JAVA-2705: Remove protocol v5 beta status, add v6-beta.
 - [bug] JAVA-2923: Detect and use Guava's new HostAndPort.getHost method.
 - [bug] JAVA-2922: Switch to modern framing format inside a channel handler.
 - [bug] JAVA-2924: Consider protocol version unsupported when server requires USE_BETA flag for it.
 
-## 3.10.2
+### 3.10.2
 
 - [bug] JAVA-2860: Avoid NPE if channel initialization crashes.
 
-## 3.10.1
+### 3.10.1
 
 - [bug] JAVA-2857: Fix NPE when built statements without parameters are logged at TRACE level.
 - [bug] JAVA-2843: Successfully parse DSE table schema in OSS driver.
 
-## 3.10.0
+### 3.10.0
 
 - [improvement] JAVA-2676: Don't reschedule flusher after empty runs
 - [new feature] JAVA-2772: Support new protocol v5 message format
 
-## 3.9.0
+### 3.9.0
 
 - [bug] JAVA-2627: Avoid logging error message including stack trace in request handler.
 - [new feature] JAVA-2706: Add now_in_seconds to protocol v5 query messages.
 - [improvement] JAVA-2730: Add support for Cassandra® 4.0 table options
 - [improvement] JAVA-2702: Transient Replication Support for Cassandra® 4.0
 
 
-## 3.8.0
+### 3.8.0
 
 - [new feature] JAVA-2356: Support for DataStax Cloud API.
 - [improvement] JAVA-2483: Allow to provide secure bundle via URL.

docs/_utils/javadoc.sh

@@ -12,5 +12,6 @@ fi
 
 # Generate javadoc
 mvn javadoc:javadoc
+[ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
 mkdir -p "$OUTPUT_DIR"
 mv -f driver-core/target/site/apidocs/* $OUTPUT_DIR

docs/source/conf.py

@@ -198,11 +198,12 @@ class DitaaLexer(BashLexer):
 TAGS = []
 smv_tag_whitelist = multiversion_regex_builder(TAGS)
 # Whitelist pattern for branches (set to None to ignore all branches)
-smv_branch_whitelist = r"^latest$"
+BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x']
+smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
 # Defines which version is considered to be the latest stable version.
 # Must be listed in smv_tag_whitelist or smv_branch_whitelist.
-smv_latest_version = 'latest'
-smv_rename_latest_version = ''
+smv_latest_version = 'scylla-3.10.2.x'
+smv_rename_latest_version = 'stable'
 # Whitelist pattern for remotes (set to None to use local branches only)
 smv_remote_whitelist = r"^origin$"
 # Pattern for released versions