Project: suggest a simple config file on project import wizard

readthedocs/projects/forms.py

@@ -191,6 +191,22 @@ def clean_tags(self):
         return tags
 
 
+class ProjectConfigForm(forms.Form):
+
+    """Simple intermediate step to communicate about the .readthedocs.yaml file."""
+
+    confirm = forms.BooleanField(
+        label="",
+        help_text="I've already added a '.readthedocs.yaml' file to my project",
+        required=True,
+    )
+
+    def __init__(self, *args, **kwargs):
+        # Remove 'user' field since it's not expected by BaseForm.
+        kwargs.pop("user")
+        super().__init__(*args, **kwargs)
+
+
 class ProjectAdvancedForm(ProjectTriggerBuildMixin, ProjectForm):
 
     """Advanced project option form."""

readthedocs/projects/views/private.py

@@ -53,6 +53,7 @@
     ProjectAdvancedForm,
     ProjectAdvertisingForm,
     ProjectBasicsForm,
+    ProjectConfigForm,
     ProjectExtraForm,
     ProjectRelationshipForm,
     RedirectForm,
@@ -260,8 +261,9 @@ class ImportWizardView(ProjectImportMixin, PrivateViewMixin, SessionWizardView):
     """
 
     form_list = [
-        ('basics', ProjectBasicsForm),
-        ('extra', ProjectExtraForm),
+        ("basics", ProjectBasicsForm),
+        ("config", ProjectConfigForm),
+        ("extra", ProjectExtraForm),
     ]
     condition_dict = {'extra': lambda self: self.is_advanced()}
 
@@ -315,9 +317,7 @@ def done(self, form_list, **kwargs):
         """
         form_data = self.get_all_cleaned_data()
         extra_fields = ProjectExtraForm.Meta.fields
-        # expect the first form; manually wrap in a list in case it's a
-        # View Object, as it is in Python 3.
-        basics_form = list(form_list)[0]
+        basics_form = form_list[0]
         # Save the basics form to create the project instance, then alter
         # attributes directly from other forms
         project = basics_form.save()

readthedocs/templates/projects/import_config.html

@@ -0,0 +1,55 @@
+{% extends "projects/import_base.html" %}
+{% load i18n %}
+
+{% block content %}
+<h3>{% trans "Project configuration file (<code>.readthedocs.yaml</code>)" %}</h3>
+
+<p class="info">
+    {% blocktrans trimmed %}
+    Make sure your project has a <code>.readthedocs.yaml</code> at the root of your repository. This file is required by Read the Docs to be able to build your documentation. You can <a href="https://docs.readthedocs.io/en/stable/config-file/v2.html">read more about this in our documentation</a>.
+    {% endblocktrans %}
+</p>
+
+<p class="info">
+    Here you have an example for a common Sphinx project:
+
+    <pre style="padding-left: 1.5rem;font-size: 0.85rem;border: 1px solid;">
+        <code>
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+        </code>
+    </pre>
+</p>
+
+{{ block.super }}
+{% endblock %}