Label for subproject select renamed "Child" => "Subproject" + help text added

readthedocs/projects/forms.py

@@ -433,7 +433,8 @@ class ProjectRelationshipForm(forms.ModelForm):
 
     class Meta:
         model = ProjectRelationship
-        fields = '__all__'
+        fields = "__all__"
+        labels = {"child": _("Subproject")}
 
     def __init__(self, *args, **kwargs):
         self.project = kwargs.pop('project')

readthedocs/projects/migrations/0094_auto_20221221_1045.py

@@ -0,0 +1,34 @@
+# Generated by Django 3.2.16 on 2022-12-21 10:45
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("projects", "0093_migrate_null_fields"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="projectrelationship",
+            name="child",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="superprojects",
+                to="projects.project",
+                verbose_name="Subproject",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="projectrelationship",
+            name="parent",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="subprojects",
+                to="projects.project",
+                verbose_name="Main project",
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -73,19 +73,22 @@ class ProjectRelationship(models.Model):
     """
     Project to project relationship.
 
-    This is used for subprojects
+    This is used for subprojects.
+
+    Terminology: We should say main project and subproject.
+    Saying "child" and "parent" only has internal, technical value.
     """
 
     parent = models.ForeignKey(
-        'projects.Project',
-        verbose_name=_('Parent'),
-        related_name='subprojects',
+        "projects.Project",
+        verbose_name=_("Main project"),
+        related_name="subprojects",
         on_delete=models.CASCADE,
     )
     child = models.ForeignKey(
-        'projects.Project',
-        verbose_name=_('Child'),
-        related_name='superprojects',
+        "projects.Project",
+        verbose_name=_("Subproject"),
+        related_name="superprojects",
         on_delete=models.CASCADE,
     )
     alias = models.SlugField(

readthedocs/templates/projects/projectrelationship_form.html

@@ -12,6 +12,12 @@
 {% block project_edit_content_header %}{% trans "Subprojects" %}{% endblock %}
 
 {% block project_edit_content %}
+    <p class="help_text">
+    {% blocktrans trimmed %}
+      Using subprojects allows you to serve multiple projects from the same domain as your main project. <a href="https://docs.readthedocs.io/en/stable/subprojects.html">Learn more</a>.
+    {% endblocktrans %}
+  </p>
+
   {% if object %}
     <form
         method="post"
@@ -38,4 +44,5 @@
       <input type="submit" value="{% trans "Add subproject" %}">
     </form>
   {% endif %}
+
 {% endblock %}