Builds: save readthedocs-build.yaml into database

I added a `Version.build_data` field that may be used from
`/_/readthedocs-config.json` to extend with data generated by the doctool at
build time if necessary.

Author: humitos

readthedocs/builds/migrations/0048_add_build_data.py

@@ -0,0 +1,22 @@
+# Generated by Django 3.2.18 on 2023-03-13 15:15
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("builds", "0047_build_default_triggered"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="version",
+            name="build_data",
+            field=models.JSONField(
+                default=None,
+                null=True,
+                verbose_name="Data generated at build time by the doctool (`readthedocs-build.yaml`).",
+            ),
+        ),
+    ]

readthedocs/builds/models.py

@@ -186,6 +186,12 @@ class Version(TimeStampedModel):
         ),
     )
 
+    build_data = models.JSONField(
+        _("Data generated at build time by the doctool (`readthedocs-build.yaml`)."),
+        default=None,
+        null=True,
+    )
+
     objects = VersionManager.from_queryset(VersionQuerySet)()
     # Only include BRANCH, TAG, UNKNOWN type Versions.
     internal = InternalVersionManager.from_queryset(partial(VersionQuerySet, internal_only=True))()

readthedocs/doc_builder/director.py

@@ -4,8 +4,6 @@
 import structlog
 import yaml
 from django.conf import settings
-from django.template.loader import render_to_string
-from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 
 from readthedocs.builds.constants import EXTERNAL
@@ -644,79 +642,17 @@ def generate_readthedocs_data_javascript(self):
             log.warning(yaml_path)
             data = yaml.safe_load(open(yaml_path, "r"))
         except Exception:
-
-            # NOTE: skip this work for now until we decide whether or not this YAML file is required
+            # NOTE: skip this work for now until we decide whether or not this YAML file is required.
+            # NOTE: decide whether or not we want this file to be mandatory and raise an exception here.
+            log.info("No `readthedocs-build.yaml` was provided.")
             return
 
-            # TODO: Improve this message
-            raise BuildUserError(
-                "The required 'readthedocs-build.yaml' file was not provided."
-            )
-
         log.info("readthedocs-build.yaml loaded.", path=yaml_path)
 
         # TODO: validate the YAML generated by the user
         # self._validate_readthedocs_data_yaml(data)
 
-        # Populate the data provided by the doctool with data we have from the build context
-        # TODO: this is the new structure that has to be defined
-        # context = {
-        #     "project": {
-        #         "slug": self.data.project.slug,
-        #     },
-        #     "version": {
-        #         "slug": self.data.version.slug,
-        #     },
-        #     "build": {
-        #         "id": self.data.build["pk"],
-        #     },
-        # }
-
-        # NOTE: this is the OLD structure.
-        # This will be changed for a new structure that we have to decide yet.
-        # I'm using the old one for now just to keep compatibility.
-        context = {
-            "ad_free": False,
-            "api_host": "http://devthedocs.org",
-            "build_date": timezone.now(),
-            "builder": "$DOCTOOL_NAME",
-            "canonical_url": self.data.project.canonical_url,
-            "commit": self.data.build["commit"],
-            "docroot": "$DOCTOOL_DOCROOT",
-            "language": self.data.project.language,
-            "page": "$DOCTOOL_PAGE",  # Can we define this dynamically via Javascript?
-            "programming_language": self.data.project.programming_language,
-            "project": self.data.project.slug,
-            "version": self.data.version.slug,
-            "source_suffix": "$DOCTOOL_SOURCE_SUFFIX",
-            "theme": "$DOCTOOL_THEME",
-            # These can be removed
-            "user_analytics_code": None,
-            "global_analytics_code": None,
-            "proxied_api_host": f"/{settings.DOC_PATH_PREFIX}",
-            "subprojects": None,
-            # TODO: remove the following ones, they are just my own tests
-            # NOTE: eventually, some of these settings should be enabled/disabled by the reader
-            "build": {
-                "id": self.data.build_pk,
-                "external_version": self.data.version.type == EXTERNAL,
-            },
-            "repository_url": self.data.project.repo,
-        }
-
-        # Update user's generated data with our own data.
-        data.update(context)
-
-        js_path = os.path.join(
-            self.data.project.artifact_path(
-                version=self.data.version.slug, type_="html"
-            ),
-            "readthedocs-data.html",
-        )
-        content = render_to_string(
-            template_name="doc_builder/readthedocs-data.html",
-            context=dict(data=context),
-        )
-        with open(js_path, "w") as f:
-            f.write(content)
-        log.info("readthedocs-data.html written.", path=js_path)
+        # Copy the YAML data into `Version.build_data`.
+        # It will be saved when the API is hit.
+        # This data will be used by the `/_/readthedocs-config.json` API endpoint.
+        self.data.version.build_data = data

readthedocs/projects/tasks/builds.py

@@ -598,6 +598,7 @@ def on_success(self, retval, task_id, args, kwargs):
                         "has_pdf": "pdf" in valid_artifacts,
                         "has_epub": "epub" in valid_artifacts,
                         "has_htmlzip": "htmlzip" in valid_artifacts,
+                        "build_data": self.data.version.build_data,
                     }
                 )
             except HttpClientError: