docs: switch from poetry to uv

uv provides better user experience.
As result of switching form poetry to uv environment preparation became seamless, to the point that `setup` step could have been completely dropped.

Author: dkropachev

.github/workflows/docs-pages.yml

@@ -23,23 +23,11 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - uses: actions/cache@v4
-        # actions/setup-python poetry cache feature requires poetry to be installed beforehand
-        # which makes use of it extremely awkward.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          path: |
-            /home/runner/.cache/pip
-            /home/runner/.cache/pypoetry
-          # python and poetry version are in docs/pyproject.toml
-          key: docs-cache-${{ runner.os }}-${{ hashFiles('docs/pyproject.toml', 'docs/Makefile') }}
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version-file: docs/pyproject.toml
-
-      - name: Set up env
-        run: make -C docs setupenv
+          working-directory: docs
+          enable-cache: true
 
       - name: Build docs
         run: make -C docs multiversion

.github/workflows/docs-pr.yml

@@ -25,23 +25,11 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - uses: actions/cache@v4
-        # actions/setup-python poetry cache feature requires poetry to be installed beforehand
-        # which makes use of it extremely awkward.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          path: |
-            /home/runner/.cache/pip
-            /home/runner/.cache/pypoetry
-          # python and poetry version are in docs/pyproject.toml
-          key: docs-cache-${{ runner.os }}-${{ hashFiles('docs/pyproject.toml', 'docs/Makefile') }}
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version-file: docs/pyproject.toml
-
-      - name: Set up env
-        run: make -C docs setupenv
+          working-directory: docs
+          enable-cache: true
 
       - name: Build docs
         run: make -C docs test

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,5 @@
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
 
+# Asyncore has been removed from python 3.12, we need to mock it until `cassandra/io/asyncorereactor.py` is dropped
+autodoc_mock_imports = ["asyncore"]