Project: suggest a simple config file on project import wizard

As part of the "Import Wizard" steps, we add an extra step now that shows a
simple suggestion for a config file v2 (the same we currently have in our
documentation) that uses `build.os: ubuntu-22.04` and `build.tools.python:
"3.11"`.

This is an initial work to show the value we can add to this wizard with
something pretty simple. There is more work required on the copy for this
intermediate step and the UX (I added a checkbox for now to force the user to
read the message, not ideal, but works for now).

Also, it would be good to find a way to highlight the YAML syntaxis using nice
colors and add more useful copy to that intermediate page.

Related #10352

Author: humitos

readthedocs/projects/forms.py

@@ -191,6 +191,21 @@ def clean_tags(self):
         return tags
 
 
+class ProjectConfigForm(forms.Form):
+
+    """Simple intermediate step to communicate about the .readthedocs.yaml file."""
+
+    confirm = forms.BooleanField(
+        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,50 @@
+{% 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 read more about this at https://docs.readthedocs.io/en/stable/config-file/v2.html
+    {% endblocktrans %}
+</p>
+
+<p class="info">
+    Here you have an example for a Sphinx project:
+
+    <code><pre>
+# .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 version of Python 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
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+    </pre></code>
+</p>
+
+{{ block.super }}
+{% endblock %}