Use the database for docs rendering

Author: charlesroelli

docs/management/commands/update_docs.py

@@ -278,6 +278,9 @@ def zipfile_inclusion_filter(file_path):
 
         json_built_dir = parent_build_dir / "_built" / "json"
         documents = gen_decoded_documents(json_built_dir)
+        with open(json_built_dir / "globalcontext.json") as context:
+            release.global_context = json.load(context)
+        release.save(update_fields=["global_context"])
         release.sync_to_db(documents)
 
     def update_git(self, url, destdir, changed_dir="."):

docs/migrations/0008_documentrelease_global_context.py

@@ -0,0 +1,44 @@
+# Generated by Django 6.0.4 on 2026-05-06 09:20
+
+import json
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+def set_documentrelease_global_context(apps, schema_editor):
+    DocumentRelease = apps.get_model("docs", "DocumentRelease")
+    for doc_release in DocumentRelease.objects.filter(release__isnull=False):
+        if not doc_release.global_context:
+            try:
+                with open(
+                    settings.DOCS_BUILD_ROOT
+                    / doc_release.lang
+                    / doc_release.release.version
+                    / "_built"
+                    / "json"
+                    / "globalcontext.json"
+                ) as context:
+                    doc_release.global_context = json.load(context)
+            except FileNotFoundError:
+                pass
+            else:
+                doc_release.save(update_fields=["global_context"])
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("docs", "0007_add_docs_search_vector"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="documentrelease",
+            name="global_context",
+            field=models.JSONField(default=dict),
+        ),
+        migrations.RunPython(
+            set_documentrelease_global_context, migrations.RunPython.noop, elidable=True
+        ),
+    ]

docs/models.py

@@ -1,6 +1,5 @@
 import datetime
 import html
-import json
 import logging
 import operator
 from functools import partial, reduce
@@ -111,6 +110,7 @@ class DocumentRelease(models.Model):
         limit_choices_to={"status": "f"},
         on_delete=models.CASCADE,
     )
+    global_context = models.JSONField(default=dict)
     is_default = models.BooleanField(default=False)
 
     objects = DocumentReleaseQuerySet.as_manager()
@@ -469,7 +469,4 @@ def full_path(self):
 
     @cached_property
     def body(self):
-        """The document's body"""
-        with self.full_path.open() as fp:
-            doc = json.load(fp)
-        return doc["body"]
+        return self.metadata["body"]

docs/templates/docs/doc.html

@@ -166,11 +166,11 @@ <h3 id="breadcrumbs-header">{% translate "You are here:" %}</h3>
         <ul>
           <li>
             <a href="{% url 'document-index' lang=lang version=version host 'docs' %}">{% blocktranslate %}Django {{ version }} documentation{% endblocktranslate %}</a>
-            {% for p in doc.parents %}
-              <ul><li><a href="{{ p.link }}">{{ p.title|safe }}</a>
+            {% for p in doc.breadcrumbs %}
+              <ul><li><a href="{% url 'document-detail' lang=lang version=version url=p.path host 'docs' %}">{{ p.title|safe }}</a>
             {% endfor %}
             <ul><li>{% block current-page-title %}{{ doc.title|safe }}{% endblock %}</li></ul>
-            {% for p in doc.parents %}</li></ul>{% endfor %}
+            {% for p in doc.breadcrumbs %}</li></ul>{% endfor %}
           </li>
         </ul>
       </nav>

docs/tests/test_templates.py

@@ -214,12 +214,12 @@ def _assertOGTitleEqual(self, doc, expected):
 
     def test_opengraph_title(self):
         doc = Document.objects.create(
+            metadata={"body": "test body"},
             release=DocumentRelease.objects.create(
                 lang=settings.DEFAULT_LANGUAGE_CODE,
                 release=Release.objects.create(version="5.0"),
             ),
         )
-        doc.body = "test body"  # avoids trying to load the underlying physical file
 
         for title, expected in [
             ("test title", "test title"),
@@ -231,6 +231,35 @@ def test_opengraph_title(self):
             with self.subTest(title=title):
                 self._assertOGTitleEqual(doc, f"{expected} | Django documentation")
 
+    def test_breadcrumbs_render(self):
+        doc = Document.objects.create(
+            metadata={
+                "breadcrumbs": [{"path": "releases", "title": "Release notes"}],
+                "parents": "parent",
+            },
+            release=DocumentRelease.objects.create(
+                lang=settings.DEFAULT_LANGUAGE_CODE,
+                release=Release.objects.create(version="5.0"),
+            ),
+        )
+        output = render_to_string(
+            "docs/doc.html",
+            {
+                "doc": doc.metadata,
+                "lang": settings.DEFAULT_LANGUAGE_CODE,
+                "version": "5.0",
+            },
+            request=RequestFactory().get("/"),
+        )
+        self.assertInHTML(
+            """
+            <a href="http://docs.djangoproject.localhost:8000/en/5.0/releases/">
+              Release notes
+            </a>
+            """,
+            output,
+        )
+
 
 class TemplateTagTestCase(TestCase):
     def test_search_form_renders_without_request_in_template(self):

docs/tests/test_views.py

@@ -1,4 +1,9 @@
+import json
+import os
+import shutil
+import tempfile
 from http import HTTPStatus
+from pathlib import Path
 
 from django.conf import settings
 from django.contrib.sites.models import Site
@@ -335,3 +340,102 @@ def test_security_txt(self):
         self.assertEqual(response.status_code, HTTPStatus.OK)
         self.assertEqual(response["Content-Type"], "text/plain")
         self.assertIn("Expires:", response.content.decode())
+
+
+class DocumentViewTestCase(TestCase):
+    def test_document_renders_from_database(self):
+        doc = Document.objects.create(
+            metadata={
+                "body": "document rendered from database",
+            },
+            path="document",
+            release=DocumentRelease.objects.create(
+                is_default=True,
+                lang=settings.DEFAULT_LANGUAGE_CODE,
+                release=Release.objects.create(version="5.0"),
+            ),
+        )
+        response = self.client.get(
+            "/en/5.0/document/",
+            headers={"host": "docs.djangoproject.localhost:8000"},
+        )
+        self.assertEqual(response.status_code, HTTPStatus.OK)
+        self.assertContains(response, "document rendered from database")
+
+    def test_document_renders_from_filesystem(self):
+        DocumentRelease.objects.create(
+            is_default=True,
+            lang=settings.DEFAULT_LANGUAGE_CODE,
+            release=Release.objects.create(version="5.0"),
+        )
+        tmp_docs_build_root = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, tmp_docs_build_root)
+        os.makedirs(
+            tmp_docs_build_root
+            / settings.DEFAULT_LANGUAGE_CODE
+            / "5.0"
+            / "_built"
+            / "json"
+        )
+        with open(
+            tmp_docs_build_root
+            / settings.DEFAULT_LANGUAGE_CODE
+            / "5.0"
+            / "_built"
+            / "json"
+            / "filesystem.fjson",
+            "w",
+        ) as json_file:
+            json_file.write(json.dumps({"body": "document rendered from filesystem"}))
+        with self.settings(DOCS_BUILD_ROOT=tmp_docs_build_root):
+            response = self.client.get(
+                "/en/5.0/filesystem/",
+                headers={"host": "docs.djangoproject.localhost:8000"},
+            )
+            self.assertEqual(response.status_code, HTTPStatus.OK)
+            self.assertContains(response, "document rendered from filesystem")
+
+    def test_filesystem_rendering_template(self):
+        DocumentRelease.objects.create(
+            is_default=True,
+            lang=settings.DEFAULT_LANGUAGE_CODE,
+            release=Release.objects.create(version="5.0"),
+        )
+        tmp_docs_build_root = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, tmp_docs_build_root)
+        os.makedirs(
+            tmp_docs_build_root
+            / settings.DEFAULT_LANGUAGE_CODE
+            / "5.0"
+            / "_built"
+            / "json"
+        )
+        with open(
+            tmp_docs_build_root
+            / settings.DEFAULT_LANGUAGE_CODE
+            / "5.0"
+            / "_built"
+            / "json"
+            / "genindex.fjson",
+            "w",
+        ) as json_file:
+            json_file.write("{}")
+        with self.settings(DOCS_BUILD_ROOT=tmp_docs_build_root):
+            response = self.client.get(
+                "/en/5.0/genindex/",
+                headers={"host": "docs.djangoproject.localhost:8000"},
+            )
+            self.assertEqual(response.status_code, HTTPStatus.OK)
+            self.assertTemplateUsed(response, "docs/genindex.html")
+
+    def test_nonexistent_document(self):
+        DocumentRelease.objects.create(
+            is_default=True,
+            lang=settings.DEFAULT_LANGUAGE_CODE,
+            release=Release.objects.create(version="5.0"),
+        )
+        response = self.client.get(
+            "/en/5.0/nonexistent/",
+            headers={"host": "docs.djangoproject.localhost:8000"},
+        )
+        self.assertEqual(response.status_code, HTTPStatus.NOT_FOUND)

docs/views.py

@@ -1,4 +1,3 @@
-import datetime
 import json
 
 from django.conf import settings
@@ -53,35 +52,44 @@ def document(request, lang, version, url):
     if version == "stable":
         version = canonical_version
 
-    docroot = get_doc_root_or_404(lang, version)
-    doc_path = get_doc_path_or_404(docroot, url)
     try:
         release = DocumentRelease.objects.get_by_version_and_lang(version, lang)
     except DocumentRelease.DoesNotExist:
         raise Http404
 
+    try:
+        document = Document.objects.get(release=release, path__in=[url, f"{url}index"])
+        doc_name = document.path
+        metadata = document.metadata
+    except Document.DoesNotExist:
+        # We won't find e.g. the genindex page nor partially
+        # translated documents in the database.
+        docroot = get_doc_root_or_404(lang, version)
+        doc_path = get_doc_path_or_404(docroot, url)
+        doc_name = str(doc_path.relative_to(docroot)).replace(str(doc_path.suffix), "")
+        try:
+            with doc_path.open("r") as f:
+                metadata = json.load(f)
+        except FileNotFoundError:
+            raise Http404
+
     if version == "dev":
         rtd_version = "latest"
     else:
         rtd_version = version + ".x"
 
     template_names = [
-        "docs/%s.html"
-        % str(doc_path.relative_to(docroot)).replace(str(doc_path.suffix), ""),
+        f"docs/{doc_name}.html",
         "docs/doc.html",
     ]
 
-    def load_json_file(path):
-        with path.open("r") as f:
-            return json.load(f)
-
     available_languages = DocumentRelease.objects.get_available_languages_by_version(
         version
     )
 
     context = {
-        "doc": load_json_file(doc_path),
-        "env": load_json_file(docroot / "globalcontext.json"),
+        "doc": metadata,
+        "env": release.global_context,
         "lang": lang,
         "version": version,
         "canonical_version": canonical_version,
@@ -90,9 +98,6 @@ def load_json_file(path):
         "release": release,
         "rtd_version": rtd_version,
         "docurl": url,
-        "update_date": datetime.datetime.fromtimestamp(
-            (docroot / "last_build").stat().st_mtime
-        ),
         "redirect_from": request.GET.get("from", None),
     }
     response = render(request, template_names, context)