Addons: allow users to define root_selector from the WebUI (#11181)

* Addons: allow users to define `root_selector` from the WebUI

We are using `[role=main]` as the default root selector. However, there are
documentation tools that don't define it. This PR exposes the
`doc_diff_root_selector` to users to they can define a custom selector that work
for their documentation tool.

Reference readthedocs/addons#263

* Minor fix to tests

* Add a placeholder to show the default value

* Update migrations

* Migrations fixed

Author: humitos

readthedocs/projects/forms.py

@@ -587,6 +587,7 @@ class Meta:
             "project",
             "analytics_enabled",
             "doc_diff_enabled",
+            "doc_diff_root_selector",
             "external_version_warning_enabled",
             "flyout_enabled",
             "flyout_sorting",
@@ -605,6 +606,11 @@ class Meta:
                 "Show a notification on non-stable and latest versions"
             ),
         }
+        widgets = {
+            "doc_diff_root_selector": forms.TextInput(
+                attrs={"placeholder": "[role=main]"}
+            ),
+        }
 
     def __init__(self, *args, **kwargs):
         self.project = kwargs.pop("project", None)

readthedocs/projects/migrations/0119_alter_addonsconfig_flyout_sorting_custom_pattern_and_more.py

@@ -0,0 +1,37 @@
+# Generated by Django 4.2.10 on 2024-03-12 09:34
+
+from django.db import migrations, models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy
+
+    dependencies = [
+        ("projects", "0118_addons_flyout_sorting"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="addonsconfig",
+            name="flyout_sorting_custom_pattern",
+            field=models.CharField(
+                blank=True,
+                default=None,
+                help_text='Sorting pattern supported by BumpVer (<a href="https://github.com/mbarkhau/bumpver#pattern-examples">See examples</a>)',
+                max_length=32,
+                null=True,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="historicaladdonsconfig",
+            name="flyout_sorting_custom_pattern",
+            field=models.CharField(
+                blank=True,
+                default=None,
+                help_text='Sorting pattern supported by BumpVer (<a href="https://github.com/mbarkhau/bumpver#pattern-examples">See examples</a>)',
+                max_length=32,
+                null=True,
+            ),
+        ),
+    ]

readthedocs/projects/migrations/0120_docdiff_helptext.py

@@ -0,0 +1,34 @@
+# Generated by Django 4.2.10 on 2024-03-04 12:02
+
+from django.db import migrations, models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy
+    dependencies = [
+        ("projects", "0119_alter_addonsconfig_flyout_sorting_custom_pattern_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="addonsconfig",
+            name="doc_diff_root_selector",
+            field=models.CharField(
+                blank=True,
+                help_text="CSS selector for the main content of the page",
+                max_length=128,
+                null=True,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="historicaladdonsconfig",
+            name="doc_diff_root_selector",
+            field=models.CharField(
+                blank=True,
+                help_text="CSS selector for the main content of the page",
+                max_length=128,
+                null=True,
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -173,7 +173,12 @@ class AddonsConfig(TimeStampedModel):
     doc_diff_enabled = models.BooleanField(default=True)
     doc_diff_show_additions = models.BooleanField(default=True)
     doc_diff_show_deletions = models.BooleanField(default=True)
-    doc_diff_root_selector = models.CharField(null=True, blank=True, max_length=128)
+    doc_diff_root_selector = models.CharField(
+        null=True,
+        blank=True,
+        max_length=128,
+        help_text="CSS selector for the main content of the page",
+    )
 
     # External version warning
     external_version_warning_enabled = models.BooleanField(default=True)

readthedocs/proxito/tests/responses/v0.json

@@ -103,7 +103,7 @@
     "doc_diff": {
       "enabled": true,
       "base_url": "https://project.dev.readthedocs.io/en/latest/index.html",
-      "root_selector": "[role=main]",
+      "root_selector": null,
       "inject_styles": true,
       "base_host": "",
       "base_page": ""

readthedocs/proxito/views/hosting.py

@@ -485,7 +485,7 @@ def _v0(self, project, version, build, filename, url, user):
                         )
                         if filename
                         else None,
-                        "root_selector": "[role=main]",
+                        "root_selector": project.addons.doc_diff_root_selector,
                         "inject_styles": True,
                         # NOTE: `base_host` and `base_page` are not required, since
                         # we are constructing the `base_url` in the backend instead