implement multiple .readthedocs.yml files per repo

readthedocs/api/v2/serializers.py

@@ -73,26 +73,27 @@ def get_skip(self, obj):
 
     class Meta(ProjectSerializer.Meta):
         fields = ProjectSerializer.Meta.fields + (
-            'enable_epub_build',
-            'enable_pdf_build',
-            'conf_py_file',
-            'analytics_code',
-            'analytics_disabled',
-            'cdn_enabled',
-            'container_image',
-            'container_mem_limit',
-            'container_time_limit',
-            'install_project',
-            'use_system_packages',
-            'skip',
-            'requirements_file',
-            'python_interpreter',
-            'features',
-            'has_valid_clone',
-            'has_valid_webhook',
-            'show_advertising',
-            'environment_variables',
-            'max_concurrent_builds',
+            "enable_epub_build",
+            "enable_pdf_build",
+            "conf_py_file",
+            "analytics_code",
+            "analytics_disabled",
+            "cdn_enabled",
+            "container_image",
+            "container_mem_limit",
+            "container_time_limit",
+            "install_project",
+            "use_system_packages",
+            "skip",
+            "requirements_file",
+            "python_interpreter",
+            "features",
+            "has_valid_clone",
+            "has_valid_webhook",
+            "show_advertising",
+            "environment_variables",
+            "max_concurrent_builds",
+            "rtd_conf_file",
         )
 
 

readthedocs/config/config.py

@@ -1369,15 +1369,22 @@ def search(self):
         return Search(**self._config['search'])
 
 
-def load(path, env_config):
+def load(path, env_config, config_file=None):
     """
     Load a project configuration and the top-most build config for a given path.
 
     That is usually the root of the project, but will look deeper. According to
     the version of the configuration a build object would be load and validated,
     ``BuildConfigV1`` is the default.
     """
-    filename = find_one(path, CONFIG_FILENAME_REGEX)
+    if config_file is None or config_file == "":
+        filename = find_one(path, CONFIG_FILENAME_REGEX)
+    else:
+        filename = os.path.join(path, config_file)
+        if not os.path.exists(filename):
+            raise ConfigError(
+                f".readthedocs.yml not found at {config_file}", CONFIG_FILE_REQUIRED
+            )
 
     if not filename:
         raise ConfigFileNotFound(path)

readthedocs/doc_builder/config.py

@@ -56,6 +56,7 @@ def load_yaml_config(version):
         config = load_config(
             path=checkout_path,
             env_config=env_config,
+            config_file=project.rtd_conf_file,
         )
     except ConfigFileNotFound:
         # Default to use v1 with some defaults from the web interface

readthedocs/projects/forms.py

@@ -198,15 +198,16 @@ class ProjectAdvancedForm(ProjectTriggerBuildMixin, ProjectForm):
     class Meta:
         model = Project
         per_project_settings = (
-            'default_version',
-            'default_branch',
-            'privacy_level',
-            'analytics_code',
-            'analytics_disabled',
-            'show_version_warning',
-            'single_version',
-            'external_builds_enabled',
-            'external_builds_privacy_level',
+            "default_version",
+            "default_branch",
+            "privacy_level",
+            "analytics_code",
+            "analytics_disabled",
+            "show_version_warning",
+            "single_version",
+            "external_builds_enabled",
+            "external_builds_privacy_level",
+            "rtd_conf_file",
         )
         # These that can be set per-version using a config file.
         per_version_settings = (
@@ -357,6 +358,17 @@ def clean_conf_py_file(self):
             )  # yapf: disable
         return filename
 
+    def clean_rtd_conf_file(self):
+        filename = self.cleaned_data.get("rtd_conf_file", "").strip()
+        if filename and ".readthedocs.yml" not in filename:
+            raise forms.ValidationError(
+                _(
+                    "Your configuration file is invalid, make sure it contains "
+                    ".readthedocs.yml in it.",
+                ),
+            )  # yapf: disable
+        return filename
+
     def get_all_active_versions(self):
         """
         Returns all active versions.

readthedocs/projects/migrations/0096_auto_20230207_1642.py

@@ -0,0 +1,35 @@
+# Generated by Django 3.2.17 on 2023-02-07 16:42
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("projects", "0095_default_branch_helptext"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="historicalproject",
+            name="rtd_conf_file",
+            field=models.CharField(
+                blank=True,
+                default="",
+                help_text="Path from project root to <code>.readthedocs.yml</code> file (ex. <code>docs/.readthedocs.yml</code>). Leave blank if you want us to find it for you.",
+                max_length=255,
+                verbose_name=".readthedocs.yml configuration file",
+            ),
+        ),
+        migrations.AddField(
+            model_name="project",
+            name="rtd_conf_file",
+            field=models.CharField(
+                blank=True,
+                default="",
+                help_text="Path from project root to <code>.readthedocs.yml</code> file (ex. <code>docs/.readthedocs.yml</code>). Leave blank if you want us to find it for you.",
+                max_length=255,
+                verbose_name=".readthedocs.yml configuration file",
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -352,9 +352,20 @@ class Project(models.Model):
         default='',
         blank=True,
         help_text=_(
-            'Path from project root to <code>conf.py</code> file '
-            '(ex. <code>docs/conf.py</code>). '
-            'Leave blank if you want us to find it for you.',
+            "Path from project root to <code>conf.py</code> file "
+            "(ex. <code>docs/conf.py</code>). "
+            "Leave blank if you want us to find it for you.",
+        ),
+    )
+    rtd_conf_file = models.CharField(
+        _(".readthedocs.yml configuration file"),
+        max_length=255,
+        default="",
+        blank=True,
+        help_text=_(
+            "Path from project root to <code>.readthedocs.yml</code> file "
+            "(ex. <code>docs/.readthedocs.yml</code>). "
+            "Leave blank if you want us to find it for you.",
         ),
     )
 

readthedocs/rtd_tests/tests/test_api.py

@@ -686,19 +686,24 @@ class APITests(TestCase):
     def test_user_doesnt_get_full_api_return(self):
         user_normal = get(User, is_staff=False)
         user_admin = get(User, is_staff=True)
-        project = get(Project, main_language_project=None, conf_py_file='foo')
+        project = get(
+            Project, main_language_project=None, conf_py_file="foo", rtd_conf_file="bar"
+        )
         client = APIClient()
 
         client.force_authenticate(user=user_normal)
         resp = client.get('/api/v2/project/%s/' % (project.pk))
         self.assertEqual(resp.status_code, 200)
-        self.assertNotIn('conf_py_file', resp.data)
+        self.assertNotIn("conf_py_file", resp.data)
+        self.assertNotIn("rtd_conf_file", resp.data)
 
         client.force_authenticate(user=user_admin)
         resp = client.get('/api/v2/project/%s/' % (project.pk))
         self.assertEqual(resp.status_code, 200)
-        self.assertIn('conf_py_file', resp.data)
-        self.assertEqual(resp.data['conf_py_file'], 'foo')
+        self.assertIn("conf_py_file", resp.data)
+        self.assertEqual(resp.data["conf_py_file"], "foo")
+        self.assertIn("rtd_conf_file", resp.data)
+        self.assertEqual(resp.data["rtd_conf_file"], "bar")
 
     def test_project_features(self):
         user = get(User, is_staff=True)
@@ -2453,6 +2458,7 @@ def test_get_version_by_id(self):
                 "repo": "https://github.com/pypa/pip",
                 "repo_type": "git",
                 "requirements_file": None,
+                "rtd_conf_file": "",
                 "show_advertising": True,
                 "skip": False,
                 "slug": "pip",

readthedocs/rtd_tests/tests/test_config_integration.py

@@ -23,7 +23,7 @@ def create_load(config=None):
     if config is None:
         config = {}
 
-    def inner(path=None, env_config=None):
+    def inner(path=None, env_config=None, config_file=None):
         env_config_defaults = {
             'output_base': '',
             'name': '1',
@@ -97,8 +97,9 @@ def test_python_supported_versions_default_image_1_0(self, load_config):
             expected_env_config.update(img_settings)
 
         load_config.assert_called_once_with(
-                path=mock.ANY,
-                env_config=expected_env_config,
+            path=mock.ANY,
+            env_config=expected_env_config,
+            config_file="",
         )
         self.assertEqual(config.python.version, '3')