From 8659c1502fd079c1254d0ac9801271b0b0d9882b Mon Sep 17 00:00:00 2001
From: Piotr Grabowski <piotr.grabowski@scylladb.com>
Date: Thu, 12 May 2022 13:25:07 +0200
Subject: [PATCH 01/20] Pin specific version of Jinja2

Before this change, the docs failed to build with the following
error:

ImportError: cannot import name 'environmentfilter' from 'jinja2'

A fix to this problem is to explicitly pin Jinja2 version.

(cherry picked from commit cdaf75a6cf54b91f3f795aa509cf836166dad1e2)
---
 docs/pyproject.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index 170bdbf9364..d6b89004e90 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -14,6 +14,7 @@ sphinx-sitemap = "2.1.0"
 sphinx-autobuild = "0.7.1"
 Sphinx = "2.4.4"
 sphinx-multiversion-scylla = "~0.2.6"
+Jinja2 = "<3.1"
 
 [tool.poetry.dev-dependencies]
 pytest = "5.2"

From f8c3c9d398f4acf72c096879566ff8be5ead1089 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Tue, 17 May 2022 11:26:49 +0100
Subject: [PATCH 02/20] docs: update theme 1.2

docs: update dynamic slug

Add back index.md

Move custom slug to a separate PR

Fix typo

(cherry picked from commit 8feeb205fcf163d9a45dbe884fc353ef5a1a4535)
---
 .github/workflows/docs-pages.yaml | 41 ++++++++++++++++
 .github/workflows/docs-pr.yaml    | 36 ++++++++++++++
 README-dev.md                     | 17 +++++++
 docs.yaml                         | 60 ----------------------
 docs/Makefile                     | 82 +++++++++++++++++++------------
 docs/_utils/javadoc.sh            |  4 +-
 docs/_utils/setup.sh              | 11 -----
 docs/pyproject.toml               | 16 +++---
 docs/source/conf.py               | 31 ++++++++----
 9 files changed, 174 insertions(+), 124 deletions(-)
 create mode 100644 .github/workflows/docs-pages.yaml
 create mode 100644 .github/workflows/docs-pr.yaml
 create mode 100644 README-dev.md
 delete mode 100644 docs.yaml
 delete mode 100755 docs/_utils/setup.sh

diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml
new file mode 100644
index 00000000000..fc52bb0f22f
--- /dev/null
+++ b/.github/workflows/docs-pages.yaml
@@ -0,0 +1,41 @@
+name: "Docs / Publish"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
+
+on:
+  push:
+    branches:
+    - scylla-3.x
+    paths:
+    - 'docs/**'
+    - 'faq/**'
+    - 'manual/**'
+    - 'changelog/**'
+    - 'upgrade_guide/**'
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: 3.7
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Set up env
+        run: make -C docs setupenv
+      - name: Build docs
+        run: make -C docs multiversion
+      - name: Deploy docs to GitHub Pages
+        run: ./docs/_utils/deploy.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml
new file mode 100644
index 00000000000..73f1e34c65b
--- /dev/null
+++ b/.github/workflows/docs-pr.yaml
@@ -0,0 +1,36 @@
+name: "Docs / Build PR"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
+
+on:
+  pull_request:
+    branches:
+    - scylla-3.x
+    paths:
+    - 'docs/**'
+    - 'faq/**'
+    - 'manual/**'
+    - 'changelog/**'
+    - 'upgrade_guide/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: 3.7
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Set up env
+        run: make -C docs setupenv
+      - name: Build docs
+        run: make -C docs test
\ No newline at end of file
diff --git a/README-dev.md b/README-dev.md
new file mode 100644
index 00000000000..5da38fd77da
--- /dev/null
+++ b/README-dev.md
@@ -0,0 +1,17 @@
+# Building the docs
+
+The docs build instructions have been tested with Sphinx 4 and Fedora 32.
+
+## Prerequisites
+
+To build and preview the docs locally, you will need to install the following software:
+
+- Git
+- Python 3.7
+- pip
+- Java JDK 8 or above
+- Maven
+
+## Commands
+
+For more information, see [Commands](https://sphinx-theme.scylladb.com/stable/commands.html).
diff --git a/docs.yaml b/docs.yaml
deleted file mode 100644
index 7c679a0f47e..00000000000
--- a/docs.yaml
+++ /dev/null
@@ -1,60 +0,0 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-# 
-#   http://www.apache.org/licenses/LICENSE-2.0
-# 
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-title:    Java Driver
-summary:  Java Driver for Apache Cassandra®
-homepage: http://docs.datastax.com/en/developer/java-driver
-theme: datastax
-sections:
-  - title:     Manual
-    prefix:    /manual
-    sources:
-      - type:  markdown
-        files: 'manual/**/*.md'
-  - title:     Reference configuration
-    prefix:    /manual/core/configuration/reference
-    sources:
-      - type: rst
-        files: 'manual/core/configuration/reference/*.rst'
-  - title:     Changelog
-    prefix:    /changelog
-    sources:
-      - type:  markdown
-        files: 'changelog/**/*.md'
-  - title:     Upgrading
-    prefix:    /upgrade_guide
-    sources:
-      - type:  markdown
-        files: 'upgrade_guide/**/*.md'
-  - title:     FAQ
-    prefix:    /faq
-    sources:
-      - type:  markdown
-        files: 'faq/**/*.md'
-links:
-  - title: Code
-    href:  https://github.com/datastax/java-driver/
-  - title: Docs
-    href:  http://docs.datastax.com/en/developer/java-driver
-  - title: Issues
-    href:  https://datastax-oss.atlassian.net/browse/JAVA/
-  - title: Mailing List
-    href:  https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
-  - title: Releases
-    href:  https://github.com/datastax/java-driver/releases
-api_docs:
-  4.0: http://docs.datastax.com/en/drivers/java/4.0
diff --git a/docs/Makefile b/docs/Makefile
index 2cebd73728e..8401dcb26e7 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,89 +1,107 @@
 # You can set these variables from the command line.
-POETRY        = $(HOME)/.poetry/bin/poetry
+POETRY        = poetry
 SPHINXOPTS    =
 SPHINXBUILD   = $(POETRY) run sphinx-build
 PAPER         =
 BUILDDIR      = _build
-SOURCE_DIR    = _source
+SOURCEDIR     = _source
 
-# Internal variables.
+# Internal variables
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# Windows variables
+ifeq ($(OS),Windows_NT)
+    POETRY = $(APPDATA)\Python\Scripts\poetry
+endif
+
+define javadoc
+    cd .. && ./docs/_utils/javadoc.sh
+endef
 
 .PHONY: all
 all: dirhtml
 
+# Setup commands
+.PHONY: setupenv
+setupenv:
+	pip install -q poetry
+
+.PHONY: setup
+setup:
+	$(POETRY) install
+	$(POETRY) update
+	cp -TLr source $(SOURCEDIR)
+	cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'
+
+# Clean commands
 .PHONY: pristine
 pristine: clean
 	git clean -dfX
 
-.PHONY: setup
-setup:
-	./_utils/setup.sh
-	cp -TLr source $(SOURCE_DIR)
-	cd $(SOURCE_DIR) && find . -name README.md -execdir mv '{}' index.md ';'
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf $(SOURCE_DIR)/*
-
-.PHONY: preview
-preview: setup
-	cd .. && ./docs/_utils/javadoc.sh
-	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
+	rm -rf $(SOURCEDIR)/*
 
+# Generate output commands
 .PHONY: dirhtml
 dirhtml: setup
+	@$(javadoc)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
 singlehtml: setup
+	@$(javadoc)
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
+.PHONY: multiversion
+multiversion: setup
+	$(POETRY) run ./_utils/multiversion.sh
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
 .PHONY: epub
-epub: 	setup
+epub: setup
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: epub3
-epub3:	setup
+epub3:setup
 	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
 	@echo
 	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
 
 .PHONY: dummy
-dummy: 	setup
+dummy: setup
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
 
-.PHONY: linkcheck
-linkcheck: setup
-	$(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck
-
-.PHONY: multiversion
-multiversion: setup
-	@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
-	$(POETRY) run ./_utils/multiversion.sh
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+# Preview commands
+.PHONY: preview
+preview: setup
+	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --re-ignore 'api/*'
 
 .PHONY: multiversionpreview
 multiversionpreview: multiversion
-	$(POETRY) run python3 -m http.server 5500 --directory $(BUILDDIR)/dirhtml
+	$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
 
+# Test commands
 .PHONY: test
 test: setup
 	$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
\ No newline at end of file
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
\ No newline at end of file
diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh
index d7669dd1ed8..0c39996f68b 100755
--- a/docs/_utils/javadoc.sh
+++ b/docs/_utils/javadoc.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Install dependencies
-mvn install -DskipTests
+mvn install -DskipTests -T 1C
 
 # Define output folder
 OUTPUT_DIR="docs/_build/dirhtml/api"
@@ -11,7 +11,7 @@ if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then
 fi
 
 # Generate javadoc
-mvn javadoc:javadoc
+mvn javadoc:javadoc -T 1C
 [ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
 mkdir -p "$OUTPUT_DIR"
 mv -f core/target/site/apidocs/* $OUTPUT_DIR
diff --git a/docs/_utils/setup.sh b/docs/_utils/setup.sh
deleted file mode 100755
index b8f50243e4f..00000000000
--- a/docs/_utils/setup.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#! /bin/bash
-
-if pwd | egrep -q '\s'; then
-	echo "Working directory name contains one or more spaces."
-	exit 1
-fi
-
-which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; }
-which poetry || curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/1.1.3/get-poetry.py | python3 - && source ${HOME}/.poetry/env
-poetry install
-poetry update
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index d6b89004e90..d25548c641a 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -6,18 +6,14 @@ authors = ["Java Driver Contributors"]
 
 [tool.poetry.dependencies]
 python = "^3.7"
-pyyaml = "5.3"
+pyyaml = "6.0"
 pygments = "2.2.0"
-recommonmark = "0.5.0"
-sphinx-scylladb-theme = "~1.0.0"
+recommonmark = "0.7.1"
+sphinx-scylladb-theme = "~1.2.1"
 sphinx-sitemap = "2.1.0"
-sphinx-autobuild = "0.7.1"
-Sphinx = "2.4.4"
-sphinx-multiversion-scylla = "~0.2.6"
-Jinja2 = "<3.1"
-
-[tool.poetry.dev-dependencies]
-pytest = "5.2"
+sphinx-autobuild = "2021.3.14"
+Sphinx = "4.3.2"
+sphinx-multiversion-scylla = "~0.2.11"
 
 [build-system]
 requires = ["poetry>=0.12"]
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 71dbea88832..082fdef2473 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -6,14 +6,24 @@
 import yaml
 import re
 from docutils import nodes
-from sphinx.util import logging
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser, splitext, urlparse
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 
+
 # -- General configuration ------------------------------------------------
 
-# Add any Sphinx extension'¡' module names here, as strings. They can be
+# Build documentation for the following tags and branches
+TAGS = []
+BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x']
+# Set the latest version.
+LATEST_VERSION = 'scylla-3.11.2.x'
+# Set which versions are not released yet.
+UNSTABLE_VERSIONS = []
+# Set which versions are deprecated
+DEPRECATED_VERSIONS = ['']
+
+# Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
@@ -21,6 +31,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.githubpages',
     'sphinx.ext.extlinks',
+    'sphinx_sitemap',
     'sphinx.ext.autosectionlabel',
     'sphinx_scylladb_theme',
     'sphinx_multiversion',
@@ -113,23 +124,24 @@ def setup(app):
 
 # -- Options for multiversion extension ----------------------------------
 
-# Whitelist pattern for tags (set to None to ignore all tags)
-TAGS = []
+# Whitelist pattern for tags
 smv_tag_whitelist = multiversion_regex_builder(TAGS)
-# Whitelist pattern for branches (set to None to ignore all branches)
-BRANCHES = ['scylla-3.x', 'scylla-3.7.2.x', 'scylla-3.10.2.x']
+# Whitelist pattern for branches
 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 = 'scylla-3.10.2.x'
+smv_latest_version = LATEST_VERSION
 smv_rename_latest_version = 'stable'
 # Whitelist pattern for remotes (set to None to use local branches only)
-smv_remote_whitelist = r"^origin$"
+smv_remote_whitelist = r'^origin$'
 # Pattern for released versions
 smv_released_pattern = r'^tags/.*$'
 # Format for versioned output directories inside the build directory
 smv_outputdir_format = '{ref.name}'
 
+# -- Options for sitemap extension ---------------------------------------
+
+sitemap_url_scheme = 'stable/{link}'
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -148,7 +160,8 @@ def setup(app):
     'github_repository': 'scylladb/java-driver',
     'github_issues_repository': 'scylladb/java-driver',
     'hide_edit_this_page_button': 'false',
-    'hide_sidebar_index': 'false',
+    'versions_unstable': UNSTABLE_VERSIONS,
+    'versions_deprecated': DEPRECATED_VERSIONS,
     'hide_version_dropdown': ['scylla-3.x'],
 }
 

From d92e6df5a54994013b115395d8c28e900777be9a Mon Sep 17 00:00:00 2001
From: Piotr Grabowski <piotr.grabowski@scylladb.com>
Date: Tue, 24 May 2022 13:46:29 +0200
Subject: [PATCH 03/20] Add Java Driver 4.x branches to documentation

Add Java Driver 4.x branches to the list of generated documentation
and bump the LATEST_VERSION variable.

(cherry picked from commit 76f771528db530c8af7f38551869fcf0d13ce567)
---
 docs/source/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 082fdef2473..2d7b1062a54 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -15,9 +15,9 @@
 
 # Build documentation for the following tags and branches
 TAGS = []
-BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x']
+BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x', 'scylla-4.7.2.x', 'scylla-4.10.0.x', 'scylla-4.11.1.x', 'scylla-4.12.0.x', 'scylla-4.13.0.x']
 # Set the latest version.
-LATEST_VERSION = 'scylla-3.11.2.x'
+LATEST_VERSION = 'scylla-4.13.0.x'
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = []
 # Set which versions are deprecated

From f4d4d797aa0ac7bc5572bbb3ba3d2479259ad6f0 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 19 Aug 2022 18:00:39 +0100
Subject: [PATCH 04/20] docs: update theme 1.3

(cherry picked from commit d2e261bcf437bd4863ce22215fdf5a4bfbf1f7de)
---
 .github/workflows/docs-pages.yaml | 2 ++
 docs/Makefile                     | 6 ++++++
 docs/_utils/multiversion.sh       | 4 ++--
 docs/_utils/redirections.yaml     | 1 -
 docs/_utils/redirects.yaml        | 0
 docs/pyproject.toml               | 5 +++--
 docs/source/conf.py               | 7 +------
 7 files changed, 14 insertions(+), 11 deletions(-)
 delete mode 100644 docs/_utils/redirections.yaml
 create mode 100644 docs/_utils/redirects.yaml

diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml
index fc52bb0f22f..b40bb391062 100644
--- a/.github/workflows/docs-pages.yaml
+++ b/.github/workflows/docs-pages.yaml
@@ -33,6 +33,8 @@ jobs:
           java-version: 1.8
       - name: Set up env
         run: make -C docs setupenv
+      - name: Build redirects
+        run: make -C docs redirects
       - name: Build docs
         run: make -C docs multiversion
       - name: Deploy docs to GitHub Pages
diff --git a/docs/Makefile b/docs/Makefile
index 8401dcb26e7..f7c59bcd79b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -95,6 +95,12 @@ preview: setup
 multiversionpreview: multiversion
 	$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
 
+.PHONY: redirects
+redirects: setup
+	$(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
 # Test commands
 .PHONY: test
 test: setup
diff --git a/docs/_utils/multiversion.sh b/docs/_utils/multiversion.sh
index 19270f32932..89895a896c6 100755
--- a/docs/_utils/multiversion.sh
+++ b/docs/_utils/multiversion.sh
@@ -1,5 +1,5 @@
 #! /bin/bash	
 
 cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
-    --pre-build './docs/_utils/javadoc.sh' \
-    --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'"
+    --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'" \
+    --post-build './docs/_utils/javadoc.sh'
diff --git a/docs/_utils/redirections.yaml b/docs/_utils/redirections.yaml
deleted file mode 100644
index 0e5f1ff9e07..00000000000
--- a/docs/_utils/redirections.yaml
+++ /dev/null
@@ -1 +0,0 @@
-api: /api/overview-summary.html
diff --git a/docs/_utils/redirects.yaml b/docs/_utils/redirects.yaml
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index d25548c641a..580711c9f9b 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -9,11 +9,12 @@ python = "^3.7"
 pyyaml = "6.0"
 pygments = "2.2.0"
 recommonmark = "0.7.1"
-sphinx-scylladb-theme = "~1.2.1"
+redirects_cli ="~0.1.2"
+sphinx-scylladb-theme = "~1.3.1"
 sphinx-sitemap = "2.1.0"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "4.3.2"
-sphinx-multiversion-scylla = "~0.2.11"
+sphinx-multiversion-scylla = "~0.2.12"
 
 [build-system]
 requires = ["poetry>=0.12"]
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2d7b1062a54..717cc4924e2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -21,7 +21,7 @@
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = []
 # Set which versions are deprecated
-DEPRECATED_VERSIONS = ['']
+DEPRECATED_VERSIONS = []
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -117,11 +117,6 @@ def setup(app):
 # Prefix added to all the URLs generated in the 404 page.
 notfound_urls_prefix = ''
 
-# -- Options for redirect extension ---------------------------------------
-
-# Read a YAML dictionary of redirections and generate an HTML file for each
-redirects_file = "_utils/redirections.yaml"
-
 # -- Options for multiversion extension ----------------------------------
 
 # Whitelist pattern for tags

From 79eccb7bf1a775eeeb78afa92676738eccc28499 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Tue, 29 Nov 2022 19:13:23 +0000
Subject: [PATCH 05/20] fix: redirection to api reference

Fix javadoc redirect

Fix

(cherry picked from commit a9fcffb44873eb938eb0312106d0c83de8f8e4dd)
---
 docs/Makefile       |  12 ++---
 docs/pyproject.toml |   4 +-
 docs/source/conf.py | 104 +++++++++++++++++++++++++-------------------
 3 files changed, 66 insertions(+), 54 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index f7c59bcd79b..63c08467e70 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -18,9 +18,6 @@ ifeq ($(OS),Windows_NT)
     POETRY = $(APPDATA)\Python\Scripts\poetry
 endif
 
-define javadoc
-    cd .. && ./docs/_utils/javadoc.sh
-endef
 
 .PHONY: all
 all: dirhtml
@@ -55,10 +52,9 @@ dirhtml: setup
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-.PHONY: singlehtml
-singlehtml: setup
-	@$(javadoc)
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+.PHONY: javadoc
+javadoc: setup
+	cd .. && ./docs/_utils/javadoc.sh
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
@@ -110,4 +106,4 @@ test: setup
 
 .PHONY: linkcheck
 linkcheck: setup
-	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
\ No newline at end of file
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index 580711c9f9b..db4a135bd8e 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -9,12 +9,14 @@ python = "^3.7"
 pyyaml = "6.0"
 pygments = "2.2.0"
 recommonmark = "0.7.1"
-redirects_cli ="~0.1.2"
+redirects_cli ="~0.1.3"
 sphinx-scylladb-theme = "~1.3.1"
 sphinx-sitemap = "2.1.0"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "4.3.2"
 sphinx-multiversion-scylla = "~0.2.12"
+setuptools = "^65.6.3"
+wheel = "^0.38.4"
 
 [build-system]
 requires = ["poetry>=0.12"]
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 717cc4924e2..9befd78554d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -9,7 +9,7 @@
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser, splitext, urlparse
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
-
+from redirects_cli import cli as redirects_cli
 
 # -- General configuration ------------------------------------------------
 
@@ -46,50 +46,6 @@
 }
 autosectionlabel_prefix_document = True
 
-class CustomCommonMarkParser(CommonMarkParser):
-    
-    def visit_document(self, node):
-        pass
-    
-    def visit_link(self, mdnode):
-        # Override to avoid checking if relative links exists
-        ref_node = nodes.reference()
-        destination = mdnode.destination
-        _, ext = splitext(destination)
-
-        url_check = urlparse(destination)
-        scheme_known = bool(url_check.scheme)
-
-        if not scheme_known and ext.replace('.', '') in self.supported:
-            destination = destination.replace(ext, '')
-        ref_node['refuri'] = destination
-        ref_node.line = self._get_line(mdnode)
-        if mdnode.title:
-            ref_node['title'] = mdnode.title
-        next_node = ref_node
-
-        self.current_node.append(next_node)
-        self.current_node = ref_node
-
-def replace_relative_links(app, docname, source):
-    result = source[0]
-    for key in app.config.replacements:
-        result = re.sub(key, app.config.replacements[key], result)
-    source[0] = result
-
-def setup(app):
-    app.add_source_parser(CustomCommonMarkParser)
-    app.add_config_value('recommonmark_config', {
-        'enable_eval_rst': True,
-        'enable_auto_toc_tree': False,
-    }, True)
-    app.add_transform(AutoStructify)
-
-    # Replace DataStax links
-    replacements = {r'https://docs.datastax.com/en/drivers/java\/(.*?)\/': "https://java-driver.docs.scylladb.com/stable/api/"}
-    app.add_config_value('replacements', replacements, True)
-    app.connect('source-read', replace_relative_links)
-
 # The master toctree document.
 master_doc = 'contents'
 
@@ -178,3 +134,61 @@ def setup(app):
 
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
+
+# -- Initialize Sphinx ----------------------------------------------
+
+class CustomCommonMarkParser(CommonMarkParser):
+    
+    def visit_document(self, node):
+        pass
+    
+    def visit_link(self, mdnode):
+        # Override MarkDownParser to avoid checking if relative links exists
+        ref_node = nodes.reference()
+        destination = mdnode.destination
+        _, ext = splitext(destination)
+
+        url_check = urlparse(destination)
+        scheme_known = bool(url_check.scheme)
+
+        if not scheme_known and ext.replace('.', '') in self.supported:
+            destination = destination.replace(ext, '')
+        ref_node['refuri'] = destination
+        ref_node.line = self._get_line(mdnode)
+        if mdnode.title:
+            ref_node['title'] = mdnode.title
+        next_node = ref_node
+
+        self.current_node.append(next_node)
+        self.current_node = ref_node
+
+def replace_relative_links(app, docname, source):
+    result = source[0]
+    for key in app.config.replacements:
+        result = re.sub(key, app.config.replacements[key], result)
+    source[0] = result
+
+def build_finished(app, exception):
+    version_name = os.getenv("SPHINX_MULTIVERSION_NAME", "")
+    version_name = "/" + version_name if version_name else ""
+    redirect_to = version_name +'/api/index.html'
+    out_file = app.outdir +'/api.html'
+    redirects_cli.create(redirect_to=redirect_to,out_file=out_file)
+
+def setup(app):
+    # Setup Markdown parser
+    app.add_source_parser(CustomCommonMarkParser)
+    app.add_config_value('recommonmark_config', {
+        'enable_eval_rst': True,
+        'enable_auto_toc_tree': False,
+    }, True)
+    app.add_transform(AutoStructify)
+
+    # Replace DataStax links
+    current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable")
+    replacements = {r'docs.datastax.com/en/drivers/java\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/"}
+    app.add_config_value('replacements', replacements, True)
+    app.connect('source-read', replace_relative_links)
+
+    # Create redirect to JavaDoc API
+    app.connect('build-finished', build_finished)

From 680de756b6187cde69c0ebcd65eab69de566e5ec Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 20 Jan 2023 18:04:30 +0000
Subject: [PATCH 06/20] Add license notice

(cherry picked from commit 7399a0ad40999f203639330d88ebaf99db6a0d10)
---
 docs/source/_templates/notice.html | 5 +++++
 docs/source/conf.py                | 3 +++
 2 files changed, 8 insertions(+)
 create mode 100644 docs/source/_templates/notice.html

diff --git a/docs/source/_templates/notice.html b/docs/source/_templates/notice.html
new file mode 100644
index 00000000000..c65ea8d802c
--- /dev/null
+++ b/docs/source/_templates/notice.html
@@ -0,0 +1,5 @@
+<div class="notice">
+    <p>ScyllaDB Java Driver is available under the <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache v2 License</a>.
+    ScyllaDB Java Driver is a fork of <a href="https://github.com/datastax/java-driver">DataStax Java Driver</a>.
+    See Copyright <a href="https://java-driver.docs.scylladb.com/stable/#license">here</a>.</p>
+</div>
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9befd78554d..0fdb6cd84cc 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -37,6 +37,9 @@
     'sphinx_multiversion',
 ]
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #

From 1e2ed281b94249bed6933a8f5f57ba22fe3004dc Mon Sep 17 00:00:00 2001
From: Piotr Grabowski <piotr.grabowski@scylladb.com>
Date: Mon, 13 Feb 2023 16:42:14 +0100
Subject: [PATCH 07/20] Add java-driver.docs.scylladb.com replacements

The links in our documentation have a hardcoded version number in them:

https://java-driver.docs.scylladb.com/scylla-3.11.2.x/api/
https://docs.datastax.com/en/drivers/java/3.11/com/datastax/driver/core/Cluster.html

Therefore, a replacement rule is needed to replace the version to a
correct version for a specific driver version we render the docs for.

Before this change, only datastax links were replaced. After this
change, java-driver.docs.scylladb.com links are also replaced.

(cherry picked from commit 8cd4d8e162226419b3d85babb57d4db7bd0ea2c1)
---
 docs/source/conf.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0fdb6cd84cc..217d58f5212 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -189,7 +189,10 @@ def setup(app):
 
     # Replace DataStax links
     current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable")
-    replacements = {r'docs.datastax.com/en/drivers/java\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/"}
+    replacements = {
+        r'docs.datastax.com/en/drivers/java\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/",
+        r'java-driver.docs.scylladb.com\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/"
+    }
     app.add_config_value('replacements', replacements, True)
     app.connect('source-read', replace_relative_links)
 

From d8345c1af39a68dded35c400693976f0fb3a4bb2 Mon Sep 17 00:00:00 2001
From: Piotr Grabowski <piotr.grabowski@scylladb.com>
Date: Wed, 15 Feb 2023 13:34:59 +0100
Subject: [PATCH 08/20] Fix java-driver.docs.scylladb.com replacement

(cherry picked from commit 511573f814770cb4faa2e7136e1d046d6f196729)
---
 docs/source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 217d58f5212..5131da98f3e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -191,7 +191,7 @@ def setup(app):
     current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable")
     replacements = {
         r'docs.datastax.com/en/drivers/java\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/",
-        r'java-driver.docs.scylladb.com\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/"
+        r'java-driver.docs.scylladb.com\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/"
     }
     app.add_config_value('replacements', replacements, True)
     app.connect('source-read', replace_relative_links)

From b0a57a5f739ed3c873508ad0e749efb9ea86285a Mon Sep 17 00:00:00 2001
From: Piotr Grabowski <piotr.grabowski@scylladb.com>
Date: Fri, 30 Jun 2023 16:39:28 +0200
Subject: [PATCH 09/20] Add 4.14.1.x and 4.15.0.x to generated docs

Add 4.14.1.x and 4.15.0.x releases to the list of versions to generate
the docs for.

(cherry picked from commit d29689596daf2f9d8002e5f71c743a088b1b95a2)
---
 docs/source/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5131da98f3e..961476dd9bc 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -15,9 +15,9 @@
 
 # Build documentation for the following tags and branches
 TAGS = []
-BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x', 'scylla-4.7.2.x', 'scylla-4.10.0.x', 'scylla-4.11.1.x', 'scylla-4.12.0.x', 'scylla-4.13.0.x']
+BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x', 'scylla-4.7.2.x', 'scylla-4.10.0.x', 'scylla-4.11.1.x', 'scylla-4.12.0.x', 'scylla-4.13.0.x', 'scylla-4.14.1.x', 'scylla-4.15.0.x']
 # Set the latest version.
-LATEST_VERSION = 'scylla-4.13.0.x'
+LATEST_VERSION = 'scylla-4.15.0.x'
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = []
 # Set which versions are deprecated

From 235c6acede3ce036172d63236ca9d9d84c82dd73 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 31 Mar 2023 15:38:41 +0100
Subject: [PATCH 10/20] docs: update theme

docs: update conf.py

docs: update conf.py

docs: Update conf.py

docs: update conf.py

docs: Update conf.py

docs: update conf.py
(cherry picked from commit 0d1f1c4512afe7bc48fec373d41f802ca17e74de)
---
 README-dev.md       | 17 ++++++++---------
 docs/Makefile       |  1 +
 docs/pyproject.toml |  2 +-
 docs/source/conf.py | 12 ++++++++++++
 4 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/README-dev.md b/README-dev.md
index 5da38fd77da..71234332fcf 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -1,17 +1,16 @@
 # Building the docs
 
-The docs build instructions have been tested with Sphinx 4 and Fedora 32.
-
 ## Prerequisites
 
-To build and preview the docs locally, you will need to install the following software:
+To build the documentation of this project, you need a UNIX-based operating system. Windows is not fully supported as it does not support symlinks.
+
+You also need the following software installed to generate the reference documentation of the driver:
 
-- Git
-- Python 3.7
-- pip
-- Java JDK 8 or above
+- Java JDK 8 or higher
 - Maven
 
-## Commands
+Once you have installed the above software, you can build and preview the documentation by following the steps outlined in the `Quickstart guide <https://sphinx-theme.scylladb.com/stable/getting-started/quickstart.html>`_.
+
+## Custom commands
 
-For more information, see [Commands](https://sphinx-theme.scylladb.com/stable/commands.html).
+To generate the reference documentation of the driver, run the command `make javadoc`. This command generates the reference documentation using the Javadoc tool in the `_build/dirhtml/<VERSION>/api` directory.
diff --git a/docs/Makefile b/docs/Makefile
index 63c08467e70..1e3374a9b00 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -43,6 +43,7 @@ pristine: clean
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(SOURCEDIR)/*
+	rm -f poetry.lock
 
 # Generate output commands
 .PHONY: dirhtml
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index db4a135bd8e..82a58bed359 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -10,7 +10,7 @@ pyyaml = "6.0"
 pygments = "2.2.0"
 recommonmark = "0.7.1"
 redirects_cli ="~0.1.3"
-sphinx-scylladb-theme = "~1.3.1"
+sphinx-scylladb-theme = "~1.4.1"
 sphinx-sitemap = "2.1.0"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "4.3.2"
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 961476dd9bc..45164d2a351 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -5,6 +5,7 @@
 from datetime import date
 import yaml
 import re
+import warnings
 from docutils import nodes
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser, splitext, urlparse
@@ -171,6 +172,13 @@ def replace_relative_links(app, docname, source):
         result = re.sub(key, app.config.replacements[key], result)
     source[0] = result
 
+
+def build_inited(app):
+    warnings.filterwarnings(
+        action="ignore",
+        message=r".*Document name contains underscores:.*",
+    )
+
 def build_finished(app, exception):
     version_name = os.getenv("SPHINX_MULTIVERSION_NAME", "")
     version_name = "/" + version_name if version_name else ""
@@ -179,6 +187,9 @@ def build_finished(app, exception):
     redirects_cli.create(redirect_to=redirect_to,out_file=out_file)
 
 def setup(app):
+    # Filter warnings
+    app.connect('builder-inited', build_inited)
+
     # Setup Markdown parser
     app.add_source_parser(CustomCommonMarkParser)
     app.add_config_value('recommonmark_config', {
@@ -198,3 +209,4 @@ def setup(app):
 
     # Create redirect to JavaDoc API
     app.connect('build-finished', build_finished)
+    

From 208efa68ec248a942964b9e09edf6ba6ea5ace20 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 31 Mar 2023 16:06:38 +0100
Subject: [PATCH 11/20] docs: update conf.py

docs: test

docs: add skip warnings option
(cherry picked from commit 2601b782e339ab0725858346918699f3da913732)
---
 docs/source/conf.py | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 45164d2a351..e61157662d6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -5,7 +5,6 @@
 from datetime import date
 import yaml
 import re
-import warnings
 from docutils import nodes
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser, splitext, urlparse
@@ -118,6 +117,7 @@
     'versions_unstable': UNSTABLE_VERSIONS,
     'versions_deprecated': DEPRECATED_VERSIONS,
     'hide_version_dropdown': ['scylla-3.x'],
+    'skip_warnings': 'document_has_underscores'
 }
 
 # If not None, a 'Last updated on:' timestamp is inserted at every page
@@ -173,12 +173,6 @@ def replace_relative_links(app, docname, source):
     source[0] = result
 
 
-def build_inited(app):
-    warnings.filterwarnings(
-        action="ignore",
-        message=r".*Document name contains underscores:.*",
-    )
-
 def build_finished(app, exception):
     version_name = os.getenv("SPHINX_MULTIVERSION_NAME", "")
     version_name = "/" + version_name if version_name else ""
@@ -187,9 +181,6 @@ def build_finished(app, exception):
     redirects_cli.create(redirect_to=redirect_to,out_file=out_file)
 
 def setup(app):
-    # Filter warnings
-    app.connect('builder-inited', build_inited)
-
     # Setup Markdown parser
     app.add_source_parser(CustomCommonMarkParser)
     app.add_config_value('recommonmark_config', {

From 63ee0f96a5b21a392b2de014ba3d7bf2bfafdd75 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 2 Jun 2023 11:19:51 +0100
Subject: [PATCH 12/20] docs: update theme 1.5

(cherry picked from commit 51ff0d5988270027e80a5d428ec0ce711619fb61)
---
 docs/pyproject.toml | 6 +++---
 docs/source/conf.py | 3 ++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index 82a58bed359..c7d7239d705 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -7,11 +7,11 @@ authors = ["Java Driver Contributors"]
 [tool.poetry.dependencies]
 python = "^3.7"
 pyyaml = "6.0"
-pygments = "2.2.0"
+pygments = "2.15.1"
 recommonmark = "0.7.1"
 redirects_cli ="~0.1.3"
-sphinx-scylladb-theme = "~1.4.1"
-sphinx-sitemap = "2.1.0"
+sphinx-scylladb-theme = "~1.5.1"
+sphinx-sitemap = "2.5.0"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "4.3.2"
 sphinx-multiversion-scylla = "~0.2.12"
diff --git a/docs/source/conf.py b/docs/source/conf.py
index e61157662d6..88b7f6a4306 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -95,7 +95,7 @@
 
 # -- Options for sitemap extension ---------------------------------------
 
-sitemap_url_scheme = 'stable/{link}'
+sitemap_url_scheme = "/stable/{link}"
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -114,6 +114,7 @@
     'github_repository': 'scylladb/java-driver',
     'github_issues_repository': 'scylladb/java-driver',
     'hide_edit_this_page_button': 'false',
+    'hide_feedback_buttons': 'false',
     'versions_unstable': UNSTABLE_VERSIONS,
     'versions_deprecated': DEPRECATED_VERSIONS,
     'hide_version_dropdown': ['scylla-3.x'],

From dd8c03b8422fc090e4ba6b1ecd4ca999d87e8516 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Tue, 19 Dec 2023 10:52:10 +0000
Subject: [PATCH 13/20] docs: update theme 1.6

(cherry picked from commit 7ab2a8f90b1e9bb7927aecb5a0cbe5cb629b9202)
---
 docs/Makefile       |  8 +-------
 docs/pyproject.toml | 12 ++++++------
 docs/source/conf.py | 12 ++++++------
 3 files changed, 13 insertions(+), 19 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 1e3374a9b00..722e738ba88 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,6 +1,6 @@
 # You can set these variables from the command line.
 POETRY        = poetry
-SPHINXOPTS    =
+SPHINXOPTS    = -j auto
 SPHINXBUILD   = $(POETRY) run sphinx-build
 PAPER         =
 BUILDDIR      = _build
@@ -13,12 +13,6 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(S
 TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 
-# Windows variables
-ifeq ($(OS),Windows_NT)
-    POETRY = $(APPDATA)\Python\Scripts\poetry
-endif
-
-
 .PHONY: all
 all: dirhtml
 
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index c7d7239d705..284caf936b0 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -5,16 +5,16 @@ description = "ScyllaDB Java Driver"
 authors = ["Java Driver Contributors"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
-pyyaml = "6.0"
+python = "^3.9"
+pyyaml = "6.0.1"
 pygments = "2.15.1"
 recommonmark = "0.7.1"
 redirects_cli ="~0.1.3"
-sphinx-scylladb-theme = "~1.5.1"
-sphinx-sitemap = "2.5.0"
+sphinx-scylladb-theme = "~1.6.1"
+sphinx-sitemap = "2.5.1"
 sphinx-autobuild = "2021.3.14"
-Sphinx = "4.3.2"
-sphinx-multiversion-scylla = "~0.2.12"
+Sphinx = "7.2.6"
+sphinx-multiversion-scylla = "~0.3.1"
 setuptools = "^65.6.3"
 wheel = "^0.38.4"
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 88b7f6a4306..fa088a87fc7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,7 +11,7 @@
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 from redirects_cli import cli as redirects_cli
 
-# -- General configuration ------------------------------------------------
+# -- General configuration
 
 # Build documentation for the following tags and branches
 TAGS = []
@@ -68,7 +68,7 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# -- Options for not found extension -------------------------------------------
+# -- Options for not found extension
 
 # Template used to render the 404.html generated by this extension.
 notfound_template =  '404.html'
@@ -76,7 +76,7 @@
 # Prefix added to all the URLs generated in the 404 page.
 notfound_urls_prefix = ''
 
-# -- Options for multiversion extension ----------------------------------
+# -- Options for multiversion extension
 
 # Whitelist pattern for tags
 smv_tag_whitelist = multiversion_regex_builder(TAGS)
@@ -93,11 +93,11 @@
 # Format for versioned output directories inside the build directory
 smv_outputdir_format = '{ref.name}'
 
-# -- Options for sitemap extension ---------------------------------------
+# -- Options for sitemap extension
 
 sitemap_url_scheme = "/stable/{link}"
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -140,7 +140,7 @@
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
 
-# -- Initialize Sphinx ----------------------------------------------
+# -- Initialize Sphinx
 
 class CustomCommonMarkParser(CommonMarkParser):
     

From 963151ed1fbaa45adb5d24d3bb4d91f7971f4ace Mon Sep 17 00:00:00 2001
From: Kefu Chai <kefu.chai@scylladb.com>
Date: Thu, 9 Nov 2023 15:22:05 +0800
Subject: [PATCH 14/20] docs: wrap long line for better readability

Signed-off-by: Kefu Chai <kefu.chai@scylladb.com>
(cherry picked from commit 6a5d3a7f9d37cc9f25f184d5b90169bb0901fc3d)
---
 docs/source/conf.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index fa088a87fc7..89db726917f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -15,7 +15,19 @@
 
 # Build documentation for the following tags and branches
 TAGS = []
-BRANCHES = ['scylla-3.7.2.x', 'scylla-3.10.2.x', 'scylla-3.11.0.x', 'scylla-3.11.2.x', 'scylla-4.7.2.x', 'scylla-4.10.0.x', 'scylla-4.11.1.x', 'scylla-4.12.0.x', 'scylla-4.13.0.x', 'scylla-4.14.1.x', 'scylla-4.15.0.x']
+BRANCHES = [
+    'scylla-3.7.2.x',
+    'scylla-3.10.2.x',
+    'scylla-3.11.0.x',
+    'scylla-3.11.2.x',
+    'scylla-4.7.2.x',
+    'scylla-4.10.0.x',
+    'scylla-4.11.1.x',
+    'scylla-4.12.0.x',
+    'scylla-4.13.0.x',
+    'scylla-4.14.1.x',
+    'scylla-4.15.0.x'
+]
 # Set the latest version.
 LATEST_VERSION = 'scylla-4.15.0.x'
 # Set which versions are not released yet.

From 101068271241fd6227cd7d0fc65cebf142066e48 Mon Sep 17 00:00:00 2001
From: David Garcia <davidgrui@ext.inditex.com>
Date: Tue, 19 Dec 2023 11:01:08 +0000
Subject: [PATCH 15/20] docs: update workflows

(cherry picked from commit 8dea9e264368827bd507efd641f3d626eaf58258)
---
 .github/workflows/docs-pages.yaml | 2 +-
 .github/workflows/docs-pr.yaml    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml
index b40bb391062..df35135f288 100644
--- a/.github/workflows/docs-pages.yaml
+++ b/.github/workflows/docs-pages.yaml
@@ -26,7 +26,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v3
         with:
-          python-version: 3.7
+          python-version: 3.9
       - name: Set up JDK 1.8
         uses: actions/setup-java@v1
         with:
diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml
index 73f1e34c65b..a0ffa6c2a62 100644
--- a/.github/workflows/docs-pr.yaml
+++ b/.github/workflows/docs-pr.yaml
@@ -25,7 +25,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v3
         with:
-          python-version: 3.7
+          python-version: 3.9
       - name: Set up JDK 1.8
         uses: actions/setup-java@v1
         with:

From 9b7c7f70f9ea19889697d4227ec0bb51d1c4ea92 Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Fri, 2 Feb 2024 13:39:30 +0000
Subject: [PATCH 16/20] docs: add myst parser

(cherry picked from commit 9eedcaca09d1bb5bb87452389c1eb9cc1bd9645f)
---
 docs/Makefile                         |  3 +-
 docs/pyproject.toml                   |  2 +-
 docs/source/conf.py                   | 74 +++++++++------------------
 manual/README.md                      |  2 +-
 manual/core/README.md                 |  2 +-
 manual/core/configuration/README.md   |  2 +-
 manual/core/metadata/README.md        |  2 +-
 manual/core/statements/README.md      |  2 +-
 manual/developer/README.md            |  2 +-
 manual/developer/common/README.md     |  2 +-
 manual/mapper/README.md               |  2 +-
 manual/mapper/config/README.md        |  2 +-
 manual/mapper/daos/README.md          |  2 +-
 manual/query_builder/README.md        |  2 +-
 manual/query_builder/schema/README.md |  2 +-
 15 files changed, 39 insertions(+), 64 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 722e738ba88..1dde91348bc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -25,7 +25,8 @@ setupenv:
 setup:
 	$(POETRY) install
 	$(POETRY) update
-	cp -TLr source $(SOURCEDIR)
+	@if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi
+	cp -RL source/* $(SOURCEDIR)
 	cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'
 
 # Clean commands
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index 284caf936b0..48c567743b2 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -8,7 +8,6 @@ authors = ["Java Driver Contributors"]
 python = "^3.9"
 pyyaml = "6.0.1"
 pygments = "2.15.1"
-recommonmark = "0.7.1"
 redirects_cli ="~0.1.3"
 sphinx-scylladb-theme = "~1.6.1"
 sphinx-sitemap = "2.5.1"
@@ -17,6 +16,7 @@ Sphinx = "7.2.6"
 sphinx-multiversion-scylla = "~0.3.1"
 setuptools = "^65.6.3"
 wheel = "^0.38.4"
+sphinx-scylladb-markdown = "^0.1.2"
 
 [build-system]
 requires = ["poetry>=0.12"]
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 89db726917f..7769a0c6059 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,13 +1,9 @@
 # -*- coding: utf-8 -*-
 
 import os
-import sys
-from datetime import date
-import yaml
 import re
-from docutils import nodes
-from recommonmark.transform import AutoStructify
-from recommonmark.parser import CommonMarkParser, splitext, urlparse
+from datetime import date
+from pathlib import Path
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 from redirects_cli import cli as redirects_cli
 
@@ -47,6 +43,7 @@
     'sphinx.ext.autosectionlabel',
     'sphinx_scylladb_theme',
     'sphinx_multiversion',
+    'sphinx_scylladb_markdown'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -88,6 +85,23 @@
 # Prefix added to all the URLs generated in the 404 page.
 notfound_urls_prefix = ''
 
+# -- Options for markdown extension
+scylladb_markdown_enable = True
+scylladb_markdown_recommonmark_versions = [
+    'scylla-3.7.2.x',
+    'scylla-3.10.2.x',
+    'scylla-3.11.0.x',
+    'scylla-3.11.2.x',
+    'scylla-4.7.2.x',
+    'scylla-4.10.0.x',
+    'scylla-4.11.1.x',
+    'scylla-4.12.0.x',
+    'scylla-4.13.0.x',
+    'scylla-4.14.1.x',
+    'scylla-4.15.0.x',
+]
+suppress_warnings = ["ref.any", "myst.header","myst.xref_missing"]
+
 # -- Options for multiversion extension
 
 # Whitelist pattern for tags
@@ -151,57 +165,20 @@
 
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
-
-# -- Initialize Sphinx
-
-class CustomCommonMarkParser(CommonMarkParser):
-    
-    def visit_document(self, node):
-        pass
-    
-    def visit_link(self, mdnode):
-        # Override MarkDownParser to avoid checking if relative links exists
-        ref_node = nodes.reference()
-        destination = mdnode.destination
-        _, ext = splitext(destination)
-
-        url_check = urlparse(destination)
-        scheme_known = bool(url_check.scheme)
-
-        if not scheme_known and ext.replace('.', '') in self.supported:
-            destination = destination.replace(ext, '')
-        ref_node['refuri'] = destination
-        ref_node.line = self._get_line(mdnode)
-        if mdnode.title:
-            ref_node['title'] = mdnode.title
-        next_node = ref_node
-
-        self.current_node.append(next_node)
-        self.current_node = ref_node
-
 def replace_relative_links(app, docname, source):
     result = source[0]
     for key in app.config.replacements:
         result = re.sub(key, app.config.replacements[key], result)
     source[0] = result
 
-
-def build_finished(app, exception):
+def redirect_api_page_to_javadoc(app, exception):
     version_name = os.getenv("SPHINX_MULTIVERSION_NAME", "")
     version_name = "/" + version_name if version_name else ""
     redirect_to = version_name +'/api/index.html'
-    out_file = app.outdir +'/api.html'
-    redirects_cli.create(redirect_to=redirect_to,out_file=out_file)
+    out_file = Path(app.outdir) / 'api.html'
+    redirects_cli.create(redirect_to=redirect_to, out_file=str(out_file))
 
 def setup(app):
-    # Setup Markdown parser
-    app.add_source_parser(CustomCommonMarkParser)
-    app.add_config_value('recommonmark_config', {
-        'enable_eval_rst': True,
-        'enable_auto_toc_tree': False,
-    }, True)
-    app.add_transform(AutoStructify)
-
     # Replace DataStax links
     current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable")
     replacements = {
@@ -210,7 +187,4 @@ def setup(app):
     }
     app.add_config_value('replacements', replacements, True)
     app.connect('source-read', replace_relative_links)
-
-    # Create redirect to JavaDoc API
-    app.connect('build-finished', build_finished)
-    
+    app.connect('build-finished', redirect_api_page_to_javadoc)
diff --git a/manual/README.md b/manual/README.md
index 8411eb586f0..582e5264b11 100644
--- a/manual/README.md
+++ b/manual/README.md
@@ -34,7 +34,7 @@ Common topics:
 * [Case sensitivity](case_sensitivity/)
 * [OSGi](osgi/)
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/core/README.md b/manual/core/README.md
index f7e26b4d165..bce32f27b03 100644
--- a/manual/core/README.md
+++ b/manual/core/README.md
@@ -351,7 +351,7 @@ for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) {
 
 [CASSANDRA-10145]: https://issues.apache.org/jira/browse/CASSANDRA-10145
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/core/configuration/README.md b/manual/core/configuration/README.md
index c5c23d2ea8e..0c54988cd78 100644
--- a/manual/core/configuration/README.md
+++ b/manual/core/configuration/README.md
@@ -556,7 +556,7 @@ config.getDefaultProfile().getInt(MyCustomOption.AWESOMENESS_FACTOR);
 [HOCON]: https://github.com/typesafehub/config/blob/master/HOCON.md
 [API conventions]: ../../api_conventions
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/core/metadata/README.md b/manual/core/metadata/README.md
index 0eb6a0904a5..409ec1b0ac2 100644
--- a/manual/core/metadata/README.md
+++ b/manual/core/metadata/README.md
@@ -79,7 +79,7 @@ refreshed. See the [Performance](../performance/#debouncing) page for more detai
 [Metadata]:                                     https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Metadata.html
 [Node]:                                         https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Node.html
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/core/statements/README.md b/manual/core/statements/README.md
index 8a4c2256131..08946bafb3c 100644
--- a/manual/core/statements/README.md
+++ b/manual/core/statements/README.md
@@ -83,7 +83,7 @@ can create execution profiles to capture common combinations of those options).
 [execute]:          https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#execute-com.datastax.oss.driver.api.core.cql.Statement-
 [executeAsync]:     https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#executeAsync-com.datastax.oss.driver.api.core.cql.Statement-
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/developer/README.md b/manual/developer/README.md
index 73e6cf243f2..63c1ea9d52a 100644
--- a/manual/developer/README.md
+++ b/manual/developer/README.md
@@ -37,7 +37,7 @@ from lowest to highest level:
 
 If you're reading this on GitHub, the `.nav` file in each directory contains a suggested order.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/developer/common/README.md b/manual/developer/common/README.md
index 489a46fdc1a..cda61f3f182 100644
--- a/manual/developer/common/README.md
+++ b/manual/developer/common/README.md
@@ -27,7 +27,7 @@ This covers utilities or concept that are shared throughout the codebase:
 * the [event bus](event_bus/) is used to decouple some of the internal components through
   asynchronous messaging.
   
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/mapper/README.md b/manual/mapper/README.md
index f77daf6c08d..a29f8e023c8 100644
--- a/manual/mapper/README.md
+++ b/manual/mapper/README.md
@@ -172,7 +172,7 @@ You can decide which logs to enable using the standard SLF4J mechanisms (categor
 addition, if you want no logs at all, it's possible to entirely remove them from the generated code
 with the Java compiler option `-Acom.datastax.oss.driver.mapper.logs.enabled=false`.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/mapper/config/README.md b/manual/mapper/config/README.md
index b974e5cce07..0154b03deaf 100644
--- a/manual/mapper/config/README.md
+++ b/manual/mapper/config/README.md
@@ -133,7 +133,7 @@ You will find the generated files in `build/generated/sources/annotationProcesso
 * [Java 14 records](record/)
 * [Scala](scala/)
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/mapper/daos/README.md b/manual/mapper/daos/README.md
index 705f1bc9126..673583afd15 100644
--- a/manual/mapper/daos/README.md
+++ b/manual/mapper/daos/README.md
@@ -173,7 +173,7 @@ To control how the hierarchy is scanned, annotate interfaces with [@HierarchySca
 [@HierarchyScanStrategy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/mapper/annotations/HierarchyScanStrategy.html
 [Entity Inheritance]: ../entities/#inheritance
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/query_builder/README.md b/manual/query_builder/README.md
index 037fefc81b9..f8897a25c8b 100644
--- a/manual/query_builder/README.md
+++ b/manual/query_builder/README.md
@@ -213,7 +213,7 @@ For a complete tour of the API, browse the child pages in this manual:
 [DseQueryBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseQueryBuilder.html
 [DseSchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseSchemaBuilder.html
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:
diff --git a/manual/query_builder/schema/README.md b/manual/query_builder/schema/README.md
index 0fe8edb8a6c..9443ae42629 100644
--- a/manual/query_builder/schema/README.md
+++ b/manual/query_builder/schema/README.md
@@ -65,7 +65,7 @@ element type:
 
 [SchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/querybuilder/SchemaBuilder.html
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

From eb97246ea8615577a66734be8ad3d0262eaff855 Mon Sep 17 00:00:00 2001
From: Kefu Chai <kefu.chai@scylladb.com>
Date: Thu, 11 Jul 2024 11:41:17 +0800
Subject: [PATCH 17/20] docs: triggered when on push  to scylla-3.x

this change is not cherry-picked from 4.x, as it is specific to
scylla-3.x branch.

Signed-off-by: Kefu Chai <kefu.chai@scylladb.com>
---
 .github/workflows/docs-pages.yaml | 4 ++--
 .github/workflows/docs-pr.yaml    | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml
index df35135f288..752a5c05867 100644
--- a/.github/workflows/docs-pages.yaml
+++ b/.github/workflows/docs-pages.yaml
@@ -5,7 +5,7 @@ name: "Docs / Publish"
 on:
   push:
     branches:
-    - scylla-3.x
+    - scylla-4.x
     paths:
     - 'docs/**'
     - 'faq/**'
@@ -40,4 +40,4 @@ jobs:
       - name: Deploy docs to GitHub Pages
         run: ./docs/_utils/deploy.sh
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
\ No newline at end of file
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml
index a0ffa6c2a62..bf1bf6c2973 100644
--- a/.github/workflows/docs-pr.yaml
+++ b/.github/workflows/docs-pr.yaml
@@ -5,7 +5,7 @@ name: "Docs / Build PR"
 on:
   pull_request:
     branches:
-    - scylla-3.x
+    - scylla-4.x
     paths:
     - 'docs/**'
     - 'faq/**'
@@ -33,4 +33,4 @@ jobs:
       - name: Set up env
         run: make -C docs setupenv
       - name: Build docs
-        run: make -C docs test
\ No newline at end of file
+        run: make -C docs test

From db334b952f2e774773985683eae3c2f7a2a1ff6e Mon Sep 17 00:00:00 2001
From: David Garcia <hi@davidgarcia.dev>
Date: Tue, 7 May 2024 15:28:10 +0100
Subject: [PATCH 18/20] docs: update theme

(cherry picked from commit efe510181a8c6a105f0ad953d9427ce4550eb671)
---
 .github/workflows/docs-pages.yaml | 10 ++++++----
 .github/workflows/docs-pr.yaml    |  6 +++---
 docs/pyproject.toml               |  2 +-
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml
index 752a5c05867..b560c7ca3c4 100644
--- a/.github/workflows/docs-pages.yaml
+++ b/.github/workflows/docs-pages.yaml
@@ -5,7 +5,8 @@ name: "Docs / Publish"
 on:
   push:
     branches:
-    - scylla-4.x
+    - scylla-3.x
+    - 'branch-**'
     paths:
     - 'docs/**'
     - 'faq/**'
@@ -19,14 +20,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: '3.10'
       - name: Set up JDK 1.8
         uses: actions/setup-java@v1
         with:
diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml
index bf1bf6c2973..a8dd1276c22 100644
--- a/.github/workflows/docs-pr.yaml
+++ b/.github/workflows/docs-pr.yaml
@@ -18,14 +18,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           persist-credentials: false
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: '3.10'
       - name: Set up JDK 1.8
         uses: actions/setup-java@v1
         with:
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index 48c567743b2..7665573fe12 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -9,7 +9,7 @@ python = "^3.9"
 pyyaml = "6.0.1"
 pygments = "2.15.1"
 redirects_cli ="~0.1.3"
-sphinx-scylladb-theme = "~1.6.1"
+sphinx-scylladb-theme = "~1.7.2"
 sphinx-sitemap = "2.5.1"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "7.2.6"

From 04d1a583bdc0464b8b0c4ec3f8b484a56022841a Mon Sep 17 00:00:00 2001
From: Kefu Chai <kefu.chai@scylladb.com>
Date: Fri, 12 Jul 2024 09:20:49 +0800
Subject: [PATCH 19/20] docs: suppress warning from autosectionlabel

to silence the warning from sphinx, as we have two "Dropwizard
Metrics" sections in manual/core/metrics/index.md:

```
/home/kefu/dev/scylla-java-driver/docs/_source/manual/core/metrics/index.md:291: WARNING: duplicate label manual/core/metrics/index:dropwizard metrics, other instance in /home/kefu/dev/scyll
a-java-driver/docs/_source/manual/core/metrics/index.md
```

and the warning breaks the "make test". so let's suppress the warning
at this moment.

Signed-off-by: Kefu Chai <kefu.chai@scylladb.com>
---
 docs/source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 7769a0c6059..f113e7a3b7d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -100,7 +100,7 @@
     'scylla-4.14.1.x',
     'scylla-4.15.0.x',
 ]
-suppress_warnings = ["ref.any", "myst.header","myst.xref_missing"]
+suppress_warnings = ["ref.any", "myst.header","myst.xref_missing","autosectionlabel"]
 
 # -- Options for multiversion extension
 

From 3311fc8c66d231ac4c2092ded41903b8202c64e7 Mon Sep 17 00:00:00 2001
From: Kefu Chai <kefu.chai@scylladb.com>
Date: Fri, 12 Jul 2024 09:40:15 +0800
Subject: [PATCH 20/20] manual: correct the codeblock directive

it should start with three backticks not four of them. otherwise
sphinx warns like:

```
/home/kefu/dev/scylla-java-driver/docs/_source/manual/mapper/daos/getentity/index.md:111: WARNING: Lexing literal_block '@GetEntity\nProduct asProduct(Row row);\n\n@GetEntity\nProduct firstR
owAsProduct(ResultSet resultSet);\n```\n\n' as "java" resulted in an error at token: '`'. Retrying in relaxed mode.
```

in this change, let's use three backticks. and the warning disappears.

Signed-off-by: Kefu Chai <kefu.chai@scylladb.com>
---
 manual/mapper/daos/getentity/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/manual/mapper/daos/getentity/README.md b/manual/mapper/daos/getentity/README.md
index abb7cb076c8..de9a530b558 100644
--- a/manual/mapper/daos/getentity/README.md
+++ b/manual/mapper/daos/getentity/README.md
@@ -108,7 +108,7 @@ The method can return:
 * a single entity instance. If the argument is a result set type, the generated code will extract
   the first row and convert it, or return `null` if the result set is empty.
 
-    ````java
+    ```java
     @GetEntity
     Product asProduct(Row row);