docs: forward-ports from 3.x

.github/workflows/docs-pages.yaml

@@ -0,0 +1,45 @@
+name: "Docs / Publish"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
+
+on:
+  push:
+    branches:
+    - scylla-3.x
+    - 'branch-**'
+    paths:
+    - 'docs/**'
+    - 'faq/**'
+    - 'manual/**'
+    - 'changelog/**'
+    - 'upgrade_guide/**'
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        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@v5
+        with:
+          python-version: '3.10'
+      - 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 redirects
+        run: make -C docs redirects
+      - 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 }}

.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-4.x
+    paths:
+    - 'docs/**'
+    - 'faq/**'
+    - 'manual/**'
+    - 'changelog/**'
+    - 'upgrade_guide/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - 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

README-dev.md

@@ -0,0 +1,16 @@
+# Building the docs
+
+## Prerequisites
+
+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:
+
+- Java JDK 8 or higher
+- Maven
+
+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
+
+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.

docs/Makefile

@@ -1,89 +1,105 @@
 # You can set these variables from the command line.
-POETRY        = $(HOME)/.poetry/bin/poetry
-SPHINXOPTS    =
+POETRY        = poetry
+SPHINXOPTS    = -j auto
 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
-
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 
 .PHONY: all
 all: dirhtml
 
+# Setup commands
+.PHONY: setupenv
+setupenv:
+	pip install -q poetry
+
+.PHONY: setup
+setup:
+	$(POETRY) install
+	$(POETRY) update
+	@if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi
+	cp -RL 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)/*
+	rm -f poetry.lock
 
+# 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
-	$(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."
 
+.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
+
+.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
 	$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck

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

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'

docs/pyproject.toml

@@ -5,18 +5,18 @@ description = "ScyllaDB Java Driver"
 authors = ["Java Driver Contributors"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
-pyyaml = "5.3"
-pygments = "2.2.0"
-recommonmark = "0.5.0"
-sphinx-scylladb-theme = "~1.0.0"
-sphinx-sitemap = "2.1.0"
-sphinx-autobuild = "0.7.1"
-Sphinx = "2.4.4"
-sphinx-multiversion-scylla = "~0.2.6"
-
-[tool.poetry.dev-dependencies]
-pytest = "5.2"
+python = "^3.9"
+pyyaml = "6.0.1"
+pygments = "2.15.1"
+redirects_cli ="~0.1.3"
+sphinx-scylladb-theme = "~1.7.2"
+sphinx-sitemap = "2.5.1"
+sphinx-autobuild = "2021.3.14"
+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"]

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>