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>