Addons: API response for tooltips (#11746)

Initial `addons.tooltips` object with basic data for testing purposes.

We will also want to add here:

- [x] ext-theme addons configurations for tooltips
- [x] model fields for tooltips
- [x] disable it by default for now
- [x] tests for the new API response

Required by readthedocs/addons#422
Closes readthedocs/addons#239

readthedocs/projects/forms.py

@@ -660,6 +660,10 @@ class Meta:
             "flyout_sorting_custom_pattern",
             "hotkeys_enabled",
             "search_enabled",
+            "linkpreviews_enabled",
+            "linkpreviews_root_selector",
+            "linkpreviews_doctool_name",
+            "linkpreviews_doctool_version",
             "notifications_enabled",
             "notifications_show_on_latest",
             "notifications_show_on_non_stable",
@@ -674,10 +678,17 @@ class Meta:
                 "Show a notification on non-stable versions"
             ),
             "notifications_show_on_latest": _("Show a notification on latest version"),
+            "linkpreviews_enabled": _("Enabled"),
+            "linkpreviews_root_selector": _("Root selector"),
+            "linkpreviews_doctool_name": _("Documentation tool name"),
+            "linkpreviews_doctool_version": _("Documentation tool version"),
         }
         widgets = {
             "doc_diff_root_selector": forms.TextInput(
-                attrs={"placeholder": "[role=main]"}
+                attrs={"placeholder": AddonsConfig.DOC_DIFF_DEFAULT_ROOT_SELECTOR}
+            ),
+            "linkpreviews_root_selector": forms.TextInput(
+                attrs={"placeholder": AddonsConfig.LINKPREVIEWS_DEFAULT_ROOT_SELECTOR}
             ),
         }
 

readthedocs/projects/migrations/0131_addons_linkpreviews_fields.py

@@ -0,0 +1,55 @@
+# Generated by Django 4.2.16 on 2024-11-06 09:18
+
+from django.db import migrations, models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy
+
+    dependencies = [
+        ('projects', '0130_addons_remove_old_fields'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='addonsconfig',
+            name='linkpreviews_doctool_name',
+            field=models.CharField(blank=True, choices=[('sphinx', 'Sphinx'), ('other', 'Other')], max_length=128, null=True),
+        ),
+        migrations.AddField(
+            model_name='addonsconfig',
+            name='linkpreviews_doctool_version',
+            field=models.CharField(blank=True, max_length=128, null=True),
+        ),
+        migrations.AddField(
+            model_name='addonsconfig',
+            name='linkpreviews_enabled',
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AddField(
+            model_name='addonsconfig',
+            name='linkpreviews_root_selector',
+            field=models.CharField(blank=True, max_length=128, null=True),
+        ),
+        migrations.AddField(
+            model_name='historicaladdonsconfig',
+            name='linkpreviews_doctool_name',
+            field=models.CharField(blank=True, choices=[('sphinx', 'Sphinx'), ('other', 'Other')], max_length=128, null=True),
+        ),
+        migrations.AddField(
+            model_name='historicaladdonsconfig',
+            name='linkpreviews_doctool_version',
+            field=models.CharField(blank=True, max_length=128, null=True),
+        ),
+        migrations.AddField(
+            model_name='historicaladdonsconfig',
+            name='linkpreviews_enabled',
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AddField(
+            model_name='historicaladdonsconfig',
+            name='linkpreviews_root_selector',
+            field=models.CharField(blank=True, max_length=128, null=True),
+        ),
+    ]

readthedocs/projects/models.py

@@ -145,6 +145,11 @@ class AddonsConfig(TimeStampedModel):
     """
 
     DOC_DIFF_DEFAULT_ROOT_SELECTOR = "[role=main]"
+    LINKPREVIEWS_DEFAULT_ROOT_SELECTOR = "[role=main] a.internal"
+    LINKPREVIEWS_DOCTOOL_NAME_CHOICES = (
+        ("sphinx", "Sphinx"),
+        ("other", "Other"),
+    )
 
     # Model history
     history = ExtraHistoricalRecords()
@@ -219,6 +224,21 @@ class AddonsConfig(TimeStampedModel):
     notifications_show_on_non_stable = models.BooleanField(default=True)
     notifications_show_on_external = models.BooleanField(default=True)
 
+    # Link Previews
+    linkpreviews_enabled = models.BooleanField(default=False)
+    linkpreviews_root_selector = models.CharField(null=True, blank=True, max_length=128)
+    linkpreviews_doctool_name = models.CharField(
+        choices=LINKPREVIEWS_DOCTOOL_NAME_CHOICES,
+        null=True,
+        blank=True,
+        max_length=128,
+    )
+    linkpreviews_doctool_version = models.CharField(
+        null=True,
+        blank=True,
+        max_length=128,
+    )
+
 
 class AddonSearchFilter(TimeStampedModel):
 

readthedocs/proxito/tests/responses/v1.json

@@ -160,6 +160,14 @@
       "enabled": true,
       "default_filter": "project:project/latest",
       "filters": []
+    },
+    "linkpreviews": {
+      "enabled": false,
+      "root_selector": "[role=main] a.internal",
+      "doctool": {
+        "name": null,
+        "version": null
+      }
     }
   }
 }

readthedocs/proxito/tests/test_hosting.py

@@ -722,6 +722,42 @@ def test_custom_domain_url(self):
             == "https://docs.example.com/en/latest/"
         )
 
+    def test_linkpreviews(self):
+        addons = fixture.get(
+            AddonsConfig,
+            project=self.project,
+        )
+
+        addons.linkpreviews_enabled = True
+        addons.linkpreviews_root_selector = "[role=main] a"
+        addons.linkpreviews_doctool_name = "sphinx"
+        addons.linkpreviews_doctool_version = "8.0.1"
+        addons.save()
+
+        r = self.client.get(
+            reverse("proxito_readthedocs_docs_addons"),
+            {
+                "api-version": "1.0.0",
+                "client-version": "0.6.0",
+                "url": "https://project.dev.readthedocs.io/en/latest/",
+            },
+            secure=True,
+            headers={
+                "host": "project.dev.readthedocs.io",
+            },
+        )
+        expected = {
+            "enabled": True,
+            "root_selector": "[role=main] a",
+            "doctool": {
+                "name": "sphinx",
+                "version": "8.0.1",
+            },
+        }
+
+        assert r.status_code == 200
+        assert r.json()["addons"]["linkpreviews"] == expected
+
     def test_non_existent_project(self):
         r = self.client.get(
             reverse("proxito_readthedocs_docs_addons"),

readthedocs/proxito/views/hosting.py

@@ -510,6 +510,15 @@ def _v1(self, project, version, build, filename, url, request):
                     if version
                     else None,
                 },
+                "linkpreviews": {
+                    "enabled": project.addons.linkpreviews_enabled,
+                    "root_selector": project.addons.linkpreviews_root_selector
+                    or project.addons.LINKPREVIEWS_DEFAULT_ROOT_SELECTOR,
+                    "doctool": {
+                        "name": project.addons.linkpreviews_doctool_name,
+                        "version": project.addons.linkpreviews_doctool_version,
+                    },
+                },
                 "hotkeys": {
                     "enabled": project.addons.hotkeys_enabled,
                     "doc_diff": {