docs: update theme 1.2.1

Update extensions

Lint conf.py

Fix CI warning

Fix CI warning

Fix warning

Fix warning

Author: dgarcia360

.github/workflows/docs-links.yaml

@@ -0,0 +1,34 @@
+name: "Docs / Links"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * 0" # At 00:00 on Sunday
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v1.4.1
+        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
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue

.github/workflows/docs-pages.yaml

@@ -1,4 +1,6 @@
 name: "Docs / Publish"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
 
 on:
   push:
@@ -13,20 +15,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           persist-credentials: false
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v2.3.2
+        uses: actions/setup-python@v3
         with:
           python-version: 3.7
-      - name: Setup Cassandra dependencies
-        run: sudo apt-get install gcc python-dev libev4 libev-dev
+      - name: Set up env
+        run: make -C docs setupenv
       - name: Build driver
         run: python setup.py develop
-      - name: Set up Poetry
-        run: curl -sSL https://install.python-poetry.org | python -
       - name: Build docs
         run: make -C docs multiversion
       - name: Deploy docs to GitHub Pages

.github/workflows/docs-pr.yaml

@@ -1,4 +1,6 @@
 name: "Docs / Build PR"
+# For more information,
+# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
 
 on:
   pull_request:
@@ -12,19 +14,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           persist-credentials: false
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v2.3.2
+        uses: actions/setup-python@v3
         with:
           python-version: 3.7
-      - name: Setup Cassandra dependencies
-        run: sudo apt-get install gcc python-dev libev4 libev-dev
+      - name: Set up env
+        run: make -C docs setupenv
       - name: Build driver
         run: python setup.py develop
-      - name: Set up Poetry
-        run: curl -sSL https://install.python-poetry.org | python -
       - name: Build docs
         run: make -C docs test

.lycheeignore

@@ -0,0 +1 @@
+http://127.0.0.1

docs/Makefile

@@ -1,40 +1,47 @@
+# Global variables
 # You can set these variables from the command line.
-POETRY        = $(HOME)/.local/bin/poetry
+POETRY        = poetry
 SPHINXOPTS    =
 SPHINXBUILD   = $(POETRY) run sphinx-build
 PAPER         =
 BUILDDIR      = _build
 SOURCEDIR     = .
 
-# 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) $(SOURCEDIR)
 TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
 
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
+# Windows variables
+ifeq ($(OS),Windows_NT)
+    POETRY = $(APPDATA)\Python\Scripts\poetry
+endif
 
 .PHONY: all
 all: dirhtml
 
-.PHONY: pristine
-pristine: clean
-	git clean -dfX
+# Setup commands
+.PHONY: setupenv
+setupenv:
+	pip install -q poetry
+	sudo apt-get install gcc python-dev libev4 libev-dev
 
 .PHONY: setup
 setup:
 	$(POETRY) install
 	$(POETRY) update
 
+# Clean commands
+.PHONY: pristine
+pristine: clean
+	git clean -dfX
+
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
 
-.PHONY: preview
-preview: setup
-	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
-
+# Generate output commands
 .PHONY: dirhtml
 dirhtml: setup
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -48,39 +55,39 @@ singlehtml: setup
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .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
-	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
-	@echo
-	@echo "Build finished. Dummy builder generates no files."
-
-.PHONY: linkcheck
-linkcheck: setup
-	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
-
 .PHONY: multiversion
 multiversion: setup
 	$(POETRY) run sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/dirhtml
 	@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
+
 .PHONY: multiversionpreview
 multiversionpreview: multiversion
 	$(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."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck

docs/conf.py

@@ -10,9 +10,29 @@
 
 # -- General configuration -----------------------------------------------------
 
+# Build documentation for the following tags and branches
+TAGS = ['3.21.0-scylla', '3.22.3-scylla', '3.24.8-scylla', '3.25.4-scylla']
+BRANCHES = ['master']
+# Set the latest version.
+LATEST_VERSION = '3.25.4-scylla'
+# Set which versions are not released yet.
+UNSTABLE_VERSIONS = ['master']
+# 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 = ['sphinx.ext.autodoc', 'sphinx.ext.githubpages', 'sphinx.ext.viewcode', 'sphinx_scylladb_theme', 'sphinx_multiversion', 'recommonmark']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
+    'sphinx_sitemap',
+    'sphinx_scylladb_theme',
+    'sphinx_multiversion',  # optional
+    'recommonmark',  # optional
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -60,32 +80,35 @@
 # -- Options for redirect extension --------------------------------------------
 
 # Read a YAML dictionary of redirections and generate an HTML file for each
-redirects_file = "_utils/redirections.yaml"
+redirects_file = '_utils/redirections.yaml'
 
 # -- Options for multiversion --------------------------------------------------
-# Whitelist pattern for tags (set to None to ignore all tags)
-TAGS = ['3.21.0-scylla', '3.22.3-scylla', '3.24.8-scylla', '3.25.4-scylla']
+
+# Whitelist pattern for tags
 smv_tag_whitelist = multiversion_regex_builder(TAGS)
-# Whitelist pattern for branches (set to None to ignore all branches)
-BRANCHES = ['master']
+# 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 = '3.25.4-scylla'
+smv_latest_version = LATEST_VERSION
+# Defines the new name for the 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 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.
 html_theme = 'sphinx_scylladb_theme'
 
+# -- Options for sitemap extension ---------------------------------------
+
+sitemap_url_scheme = 'stable/{link}'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -95,6 +118,8 @@
     'github_issues_repository': 'scylladb/python-driver',
     'hide_edit_this_page_button': 'false',
     'hide_version_dropdown': ['master'],
+    'versions_unstable': UNSTABLE_VERSIONS,
+    'versions_deprecated': DEPRECATED_VERSIONS,
 }
 
 # Custom sidebar templates, maps document names to template names.

docs/pyproject.toml

@@ -11,14 +11,14 @@ geomet = "0.1.2"
 gevent = "20.12.1"
 gremlinpython = "3.4.7"
 python = "^3.7"
-pyyaml = "^6.0"
+pyyaml = "6.0"
 pygments = "2.2.0"
-recommonmark = "^0.7.1"
-sphinx-autobuild = "^2021.3.14"
+recommonmark = "0.7.1"
+sphinx-autobuild = "2021.3.14"
 sphinx-sitemap = "2.1.0"
-sphinx-scylladb-theme = "~1.1.0"
-sphinx-multiversion-scylla = "~0.2.10"
-Sphinx = "^4.3.2"
+sphinx-scylladb-theme = "~1.2.1"
+sphinx-multiversion-scylla = "~0.2.11"
+Sphinx = "4.3.2"
 scales = "1.0.9"
 six = "1.15.0"