The Wire · Showcase
DJANGOPROJECT.COM FIXES SPHINX CACHING BUG BREAKING MULTI-RELEASE DOCS
By RepoJournal · Filed · About Django
The documentation build process was silently reusing cached Sphinx modules across Django versions, causing incorrect docs to ship for older releases.
djangoproject.com's update_docs command builds documentation for every supported Django version and language in a single long-running process. The problem: each version's docs/_ext/djangodocs.py was imported by bare module name, and once Python cached it in sys.modules, subsequent versions silently reused the first version's module regardless of which checkout was being built [1]. This is the kind of insidious bug that ships broken docs to production without any error signals. The fix isolates each release build in a separate subprocess [2], forcing fresh imports and eliminating the cache collision. The same PR also fixed a subprocess launch bug where running update_docs via 'python -m django' (as cron does) was failing to import the djangoproject settings package [3]. On the Django core side, the team has been systematically cleaning up documentation warnings: fixing duplicate target names and multiple toctree errors [4], [5], and disambiguating hyperlink targets [6]. They're also hardening the release process by adding reminders to bump asgiref in the release checklist [7]. Gunicorn shipped 26.0.0 with the eventlet worker removed [8], so djangoproject.com is ahead of that migration.
Action items
- → Review djangoproject.com docs for any version-specific build artifacts that may have shipped incorrectly before the fix django/djangoproject.com [plan]
- → Plan gunicorn 26.0.0 migration if using eventlet worker in production django/djangoproject.com [plan]
References
- [1] Refs #2685 -- Isolated per-release docs via a separate process to avoid Sphinx module caching. ↗ django/djangoproject.com
- [2] Refs #2685 -- Isolated per-release docs via a separate process to avoid Sphinx module caching. django/djangoproject.com
- [3] Refs #2685 -- Fixed build_doc_release subprocess call failing under "-m django". ↗ django/djangoproject.com
- [4] Fixed docs warning/errors for duplicate target name and multiple toctrees. ↗ django/django
- [5] Fixed duplicate target name in docs/internals/howto-release-django.txt. django/django
- [6] Disambiguated duplicate "Example" hyperlink targets in howto-release-django.txt. ↗ django/django
- [7] Updated howto-release-django.txt with reminder to bump asgiref. ↗ django/django
- [8] Bump gunicorn from 25.3.0 to 26.0.0 in /requirements ↗ django/djangoproject.com
FAQ
- What changed in Django on July 3, 2026?
- The documentation build process was silently reusing cached Sphinx modules across Django versions, causing incorrect docs to ship for older releases.
- What should Django teams do about it?
- Review djangoproject.com docs for any version-specific build artifacts that may have shipped incorrectly before the fix • Plan gunicorn 26.0.0 migration if using eventlet worker in production
- Which Django repositories shipped on July 3, 2026?
- django/djangoproject.com, django/django