Added ability to build specific version with update_docs command

Also added an --interactive flag to prompt before building
each version, making it possible to skip some.

Author: bmispelon

docs/management/commands/update_docs.py

@@ -16,6 +16,7 @@
 
 from django.conf import settings
 from django.core.management import BaseCommand, call_command
+from django.db.models import Q
 from django.utils.translation import to_locale
 from sphinx.application import Sphinx
 from sphinx.config import Config
@@ -39,6 +40,11 @@ def add_arguments(self, parser):
                 "version is no longer supported."
             ),
         )
+        parser.add_argument(
+            "--interactive",
+            action="store_true",
+            help="Ask before building each version",
+        )
         parser.add_argument(
             "--update-index",
             action="store_true",
@@ -53,40 +59,58 @@ def add_arguments(self, parser):
             default=False,
             help="Also invalidate downstream caches for any changed doc versions.",
         )
+        parser.add_argument(
+            "args",
+            metavar="versions",
+            nargs="*",
+            help="Which version to rebuild (all by default)",
+        )
+
+    def _get_doc_releases(self, versions, options):
+        """
+        Return a DocumentRelease queryset of all the versions that should be
+        built, based on the arguments received on the command line.
+        """
+        default_docs_version = DocumentRelease.objects.get(
+            is_default=True
+        ).release.version
+
+        # Somehow, bizarely, there's a bug in Sphinx such that if I try to
+        # build 1.0 before other versions, things fail in weird ways. However,
+        # building newer versions first works. I suspect Sphinx is hanging onto
+        # some global state. Anyway, we can work around it by making sure that
+        # "dev" builds before "1.0". This is ugly, but oh well.
+        queryset = DocumentRelease.objects.order_by("-release")
 
-    def handle(self, **kwargs):
+        # Skip translated non-stable versions to avoid a crash:
+        # https://github.com/django/djangoproject.com/issues/627
+        queryset = queryset.filter(Q(lang="en") | Q(release=default_docs_version))
+
+        if options["language"]:
+            queryset = queryset.filter(lang=options["language"])
+
+        if versions:
+            queryset = queryset.by_versions(*versions)
+
+        return queryset
+
+    def handle(self, *versions, **kwargs):
         self.verbosity = kwargs["verbosity"]
         self.update_index = kwargs["update_index"]
         self.purge_cache = kwargs["purge_cache"]
 
         self.default_builders = ["json", "djangohtml"]
-        default_docs_version = DocumentRelease.objects.get(
-            is_default=True
-        ).release.version
 
         # Keep track of which Git sources have been updated, e.g.,
         # {'1.8': True} if the 1.8 docs updated.
         self.release_docs_changed = {}
         # Only update the index if some docs rebuild.
         self.update_index_required = False
 
-        # Somehow, bizarely, there's a bug in Sphinx such that if I try to
-        # build 1.0 before other versions, things fail in weird ways. However,
-        # building newer versions first works. I suspect Sphinx is hanging onto
-        # some global state. Anyway, we can work around it by making sure that
-        # "dev" builds before "1.0". This is ugly, but oh well.
-        doc_releases = DocumentRelease.objects.order_by("-release")
-        if kwargs["language"]:
-            doc_releases = doc_releases.filter(lang=kwargs["language"])
-        for release in doc_releases:
-            # Skip translated non-stable versions to avoid a crash:
-            # https://github.com/django/djangoproject.com/issues/627
-            if (
-                release.lang != "en"
-                and not release.release.version == default_docs_version
-            ):
-                continue
-            self.build_doc_release(release, force=kwargs["force"])
+        for release in self._get_doc_releases(versions, kwargs):
+            self.build_doc_release(
+                release, force=kwargs["force"], interactive=kwargs["interactive"]
+            )
 
         if self.update_index_required:
             call_command("update_index", **{"verbosity": self.verbosity})
@@ -106,10 +130,16 @@ def handle(self, **kwargs):
                 if self.verbosity >= 1:
                     self.stdout.write("No docs changes; skipping cache purge.")
 
-    def build_doc_release(self, release, force=False):
+    def build_doc_release(self, release, force=False, interactive=False):
         # Skip not supported releases.
         if not release.is_supported and not force:
             return
+        if interactive:
+            prompt = (
+                f"About to start building docs for release {release}. Continue? Y/n "
+            )
+            if input(prompt).upper() not in {"", "Y", "YES", "OUI"}:
+                return
         if self.verbosity >= 1:
             self.stdout.write(f"Starting update for {release} at {datetime.now()}...")
 

docs/models.py

@@ -34,7 +34,7 @@
 )
 
 
-class DocumentReleaseManager(models.Manager):
+class DocumentReleaseQuerySet(models.QuerySet):
     def current(self, lang="en"):
         current = self.get(is_default=True)
         if lang != "en":
@@ -58,11 +58,21 @@ def current_version(self):
             )
         return current_version
 
-    def by_version(self, version):
-        return self.filter(
-            **{"release__isnull": True} if version == "dev" else {"release": version}
+    def _by_version_Q(self, version):
+        return (
+            models.Q(release__isnull=True)
+            if version == "dev"
+            else models.Q(release=version)
         )
 
+    def by_version(self, version):
+        return self.filter(self._by_version_Q(version))
+
+    def by_versions(self, *versions):
+        if not versions:
+            raise ValueError("by_versions() takes at least one argument")
+        return self.filter(reduce(operator.or_, map(self._by_version_Q, versions)))
+
     def get_by_version_and_lang(self, version, lang):
         return self.by_version(version).get(lang=lang)
 
@@ -86,7 +96,7 @@ class DocumentRelease(models.Model):
     )
     is_default = models.BooleanField(default=False)
 
-    objects = DocumentReleaseManager()
+    objects = DocumentReleaseQuerySet.as_manager()
 
     class Meta:
         unique_together = ("lang", "release")

docs/tests/test_models.py

@@ -111,16 +111,43 @@ def setUpTestData(cls):
         r2 = Release.objects.create(version="2.0")
         DocumentRelease.objects.bulk_create(
             DocumentRelease(lang=lang, release=release)
-            for lang, release in [("en", r1), ("en", r2), ("sv", r1), ("ar", r1)]
+            for lang, release in [
+                ("en", None),
+                ("en", r1),
+                ("en", r2),
+                ("sv", r1),
+                ("ar", r1),
+            ]
         )
 
     def test_by_version(self):
-        doc_releases = DocumentRelease.objects.by_version("1.0")
-        self.assertEqual(
-            {(r.lang, r.release.version) for r in doc_releases},
-            {("en", "1.0"), ("sv", "1.0"), ("ar", "1.0")},
+        self.assertQuerySetEqual(
+            DocumentRelease.objects.by_version("1.0"),
+            [("en", "1.0"), ("sv", "1.0"), ("ar", "1.0")],
+            transform=attrgetter("lang", "version"),
+            ordered=False,
+        )
+
+    def test_by_version_dev(self):
+        self.assertQuerySetEqual(
+            DocumentRelease.objects.by_version("dev"),
+            [("en", "dev")],
+            transform=attrgetter("lang", "version"),
+            ordered=False,
         )
 
+    def test_by_versions(self):
+        self.assertQuerySetEqual(
+            DocumentRelease.objects.by_versions("1.0", "dev"),
+            [("en", "dev"), ("en", "1.0"), ("sv", "1.0"), ("ar", "1.0")],
+            transform=attrgetter("lang", "version"),
+            ordered=False,
+        )
+
+    def test_by_versions_empty(self):
+        with self.assertRaises(ValueError):
+            DocumentRelease.objects.by_versions()
+
     def test_get_by_version_and_lang_exists(self):
         doc = DocumentRelease.objects.get_by_version_and_lang("1.0", "en")
         self.assertEqual(doc.release.version, "1.0")