Build: export READTHEDOCS_CANONICAL_URL variable

docs/user/reference/environment-variables.rst

@@ -44,6 +44,15 @@ All :doc:`build processes </builds>` have the following environment variables au
 
     :Example: ``/home/docs/checkouts/readthedocs.org/user_builds/project/envs/version``
 
+.. envvar:: READTHEDOCS_CANONICAL_URL
+
+    Canonical URL for the version it's currently building.
+    If the project has configured a :doc:`custom domain </custom-domains>` (e.g. ``docs.example.com``) it will be used in the resulting canonical URL.
+    Otherwise, the default domain will be exposed (e.g. ``.readthedocs.io``)
+
+    :Example: ``https://docs.example.com/en/latest/``
+    :Example: ``https://docs.readthedocs.io/ja/stable/``
+
 .. seealso::
 
    :doc:`/environment-variables`

readthedocs/api/v2/serializers.py

@@ -5,6 +5,7 @@
 from rest_framework import serializers
 
 from readthedocs.api.v2.utils import normalize_build_command
+from readthedocs.builds.constants import EXTERNAL
 from readthedocs.builds.models import Build, BuildCommandResult, Version
 from readthedocs.oauth.models import RemoteOrganization, RemoteRepository
 from readthedocs.projects.models import Domain, Project
@@ -124,11 +125,20 @@ class VersionAdminSerializer(VersionSerializer):
     """Version serializer that returns admin project data."""
 
     project = ProjectAdminSerializer()
+    canonical_url = serializers.SerializerMethodField()
     build_data = serializers.JSONField(required=False, write_only=True)
 
+    def get_canonical_url(self, obj):
+        return obj.project.get_docs_url(
+            lang_slug=obj.project.language,
+            version_slug=obj.slug,
+            external=obj.type == EXTERNAL,
+        )
+
     class Meta(VersionSerializer.Meta):
         fields = VersionSerializer.Meta.fields + [
             "build_data",
+            "canonical_url",
         ]
 
 

readthedocs/builds/models.py

@@ -601,7 +601,8 @@ class Meta:
         proxy = True
 
     def __init__(self, *args, **kwargs):
-        self.project = APIProject(**kwargs.pop('project', {}))
+        self.project = APIProject(**kwargs.pop("project", {}))
+        self.canonical_url = kwargs.pop("canonical_url", None)
         # These fields only exist on the API return, not on the model, so we'll
         # remove them to avoid throwing exceptions due to unexpected fields
         for key in ['resource_uri', 'absolute_url', 'downloads']:

readthedocs/doc_builder/director.py

@@ -615,6 +615,12 @@ def get_build_env_vars(self):
                 }
             )
 
+        env.update(
+            {
+                "READTHEDOCS_CANONICAL_URL": self.data.version.canonical_url,
+            }
+        )
+
         # Update environment from Project's specific environment variables,
         # avoiding to expose private environment variables
         # if the version is external (i.e. a PR build).