Set docs workflows in order

.github/workflows/docs-pages.yaml → .github/workflows/docs-pages.yml

@@ -9,28 +9,36 @@ on:
       - 'branch-**'
     paths:
       - "docs/**"
+      - ".github/workflows/docs-pages.yml"
+      - "cassandra/**"
+      - "pyproject.toml"
+      - "setup.py"
+      - "CHANGELOG.rst"
   workflow_dispatch:
 
 jobs:
   release:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v5
         with:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
           fetch-depth: 0
-      - name: Set up Python
-        uses: actions/setup-python@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: '3.10'
-      - name: Set up env
-        run: make -C docs setupenv
+          working-directory: docs
+          enable-cache: true
+
       - name: Build docs
         run: make -C docs multiversion
+
       - name: Build redirects
         run: make -C docs redirects
+
       - name: Deploy docs to GitHub Pages
         run: ./docs/_utils/deploy.sh
         env:

.github/workflows/docs-pr.yaml → .github/workflows/docs-pr.yml

@@ -3,28 +3,41 @@ name: "Docs / Build PR"
 # see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
 
 on:
-  pull_request:
+  push:
     branches:
       - master
-      - 'branch-**'
     paths:
       - "docs/**"
+      - ".github/workflows/docs-pr.yml"
+      - "cassandra/**"
+      - "pyproject.toml"
+      - "setup.py"
+      - "CHANGELOG.rst"
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs-pr.yml"
+      - "cassandra/**"
+      - "pyproject.toml"
+      - "setup.py"
+      - "CHANGELOG.rst"
   workflow_dispatch:
 
 jobs:
   build:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v5
         with:
           persist-credentials: false
           fetch-depth: 0
-      - name: Set up Python
-        uses: actions/setup-python@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: '3.10'
-      - name: Set up env
-        run: make -C docs setupenv
+          working-directory: docs
+          enable-cache: true
+
       - name: Build docs
         run: make -C docs test

.github/workflows/integration-tests.yml

@@ -5,6 +5,18 @@ on:
     branches:
       - master
       - 'branch-**'
+    paths-ignore:
+      - docs/*
+      - examples/*
+      - scripts/*
+      - .gitignore
+      - '*.rst'
+      - '*.ini'
+      - LICENSE
+      - .github/dependabot.yml
+      - .github/pull_request_template.md
+        - "*.md"
+        - .github/workflows/docs-*
   pull_request:
     paths-ignore:
      - docs/*
@@ -16,6 +28,8 @@ on:
      - LICENSE
      - .github/dependabot.yml
      - .github/pull_request_template.md
+      - "*.md"
+      - .github/workflows/docs-*     -
   workflow_dispatch:
 
 jobs:

docs/Makefile

@@ -1,8 +1,9 @@
 # Global variables
 # You can set these variables from the command line.
-POETRY        = poetry
+SHELL         = bash
+UV            = uv
 SPHINXOPTS    = -j auto
-SPHINXBUILD   = $(POETRY) run sphinx-build
+SPHINXBUILD   = $(UV) run --frozen sphinx-build
 PAPER         =
 BUILDDIR      = _build
 SOURCEDIR     = .
@@ -17,18 +18,13 @@ TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
 all: dirhtml
 
 # Setup commands
-.PHONY: setupenv
-setupenv:
-	pip install -q poetry
-	sudo apt-get install gcc python3-dev libev4 libev-dev
-
-.PHONY: setup
-setup:
-	$(POETRY) install
+#.PHONY: setupenv
+#setupenv:
+#	uv pip install -r <(uv pip compile pyproject.toml)
 
 .PHONY: update
 update:
-	$(POETRY) update
+	$(UV) update
 
 # Clean commands
 .PHONY: pristine
@@ -41,58 +37,58 @@ clean:
 
 # Generate output commands
 .PHONY: dirhtml
-dirhtml: setup
+dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml: setup
+singlehtml:
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: epub
-epub: setup
+epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: epub3
-epub3: setup
+epub3:
 	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
 	@echo
 	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
 
 .PHONY: multiversion
-multiversion: setup
-	$(POETRY) run sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/dirhtml
+multiversion:
+	$(UV) run --frozen sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: redirects
-redirects: setup
-	$(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
+redirects:
+	$(UV) run --frozen redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(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
+preview:
+	$(UV) run --frozen sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
 
 .PHONY: multiversionpreview
 multiversionpreview: multiversion
-	$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
+	$(UV) run --frozen python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
 
 # Test commands
 .PHONY: test
-test: setup
+test:
 	$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: linkcheck
-linkcheck: setup
+linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
 

docs/conf.py

@@ -65,7 +65,16 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    ".venv",
+    ".venv/**",
+    "**/site-packages/**",
+    "**/*.dist-info/**",
+    "**/licenses/**",
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -134,3 +143,9 @@
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
 
+autodoc_mock_imports = [
+    # Asyncore has been removed from python 3.12, we need to mock it until `cassandra/io/asyncorereactor.py` is dropped
+    "asyncore",
+    # Since driver is not built, binary modules also not built, so we need to mock them
+    "cassandra.io.libevwrapper"
+]