chore: pin to Python 3.12 for docs commands only; fix contributing do…

…cs (#3953)

* docs: fix command for installing dev requirements

* pin to Python 3.12 for docs commands

* docs: remove outdated URL for local documentation serving

CONTRIBUTING.rst

@@ -40,12 +40,12 @@ the environment will bootstrap itself automatically. The steps below are for loc
 #. Install `uv <https://docs.astral.sh/uv/getting-started/installation/>`_:
 
 #. Run ``make install`` to create a `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_
-   and install the required development dependencies or run the uv sync command manually:
+   and install the required development dependencies or run the ``uv sync`` command manually:
 
    .. code-block:: shell
-        :caption: Installing the documentation dependencies
+        :caption: Installing the development dependencies
 
-        uv install
+        uv sync
 
 
 .. tip:: Many modern IDEs like PyCharm or VS Code will enable the uv-managed virtualenv that is created in step 2

Makefile

@@ -29,7 +29,7 @@ upgrade:       										## Upgrade all dependencies to the latest stable versio
 
 .PHONY: install
 install:
-	@uv sync --python 3.12
+	@uv sync
 
 .PHONY: clean
 clean: 												## Cleanup temporary build artifacts
@@ -121,10 +121,12 @@ check-all: lint test-all coverage                   ## Run all linting, tests, a
 # =============================================================================
 # Docs
 # =============================================================================
+# XXX: docs commands are pinned to Python 3.12 due to picologging not being compatible with 3.13
+
 .PHONY: docs-install
 docs-install: 										## Install docs dependencies
 	@echo "=> Installing documentation dependencies"
-	@uv install --group docs
+	@uv sync --python 3.12 --group docs
 	@echo "=> Installed documentation dependencies"
 
 docs-clean: 										## Dump the existing built docs
@@ -134,16 +136,16 @@ docs-clean: 										## Dump the existing built docs
 
 docs-serve: docs-clean 								## Serve the docs locally
 	@echo "=> Serving documentation"
-	uv run sphinx-autobuild docs docs/_build/ -j auto --watch litestar --watch docs --watch tests --watch CONTRIBUTING.rst --open-browser
+	uv run --python 3.12 sphinx-autobuild docs docs/_build/ -j auto --watch litestar --watch docs --watch tests --watch CONTRIBUTING.rst --open-browser
 
 docs: docs-clean 									## Dump the existing built docs and rebuild them
 	@echo "=> Building documentation"
-	@uv run sphinx-build -M html docs docs/_build/ -E -a -j auto -W --keep-going
+	@uv run --python 3.12 sphinx-build -M html docs docs/_build/ -E -a -j auto -W --keep-going
 
 .PHONY: docs-linkcheck
 docs-linkcheck: 									## Run the link check on the docs
-	@uv run sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_ignore='http://.*','https://.*'
+	@uv run --python 3.12 sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_ignore='http://.*','https://.*'
 
 .PHONY: docs-linkcheck-full
 docs-linkcheck-full: 									## Run the full link check on the docs
-	@uv run sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_anchors=0
+	@uv run --python 3.12 sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_anchors=0