Import project: suggest a config file (yaml)

I tried to add the intermediate page where we suggest a common Sphinx YAML file
for the user to copy and paste.

I found the pattern a little hard to follow. The base template didn't have all
the blocks I needed, so I added some more but I don't feel comfortable with
them.

I also had to create a block to overwrite the CSS classes of the main div, which
sounds weird to me as well.

Besides, I'm not sure how to use the CSS classes to achieve what I need: syntax
highlighting, smaller text, etc.

Author: humitos

readthedocsext/theme/templates/projects/import_base.html

@@ -6,9 +6,9 @@
 {% block title %}{% trans "Add Project" %}{% endblock %}
 
 {% block content %}
-  {% block project_add_content %}
     <div class="ui very padded centered stackable grid">
-      <div class="ui ten wide tablet six wide computer column">
+    {% block project_add_content %}
+      <div class="{% block project_add_css_classes %}ui ten wide tablet six wide computer column{% endblock project_add_css_classes %}">
 
         {% block project_add_content_header %}
           <h1 class="ui medium header">
@@ -22,6 +22,9 @@ <h1 class="ui medium header">
           </h1>
         {% endblock project_add_content_header %}
 
+        {% block project_add_content_main %}
+        {% endblock project_add_content_main %}
+
         <form class="ui form" action="{% url "projects_import_manual" %}" method="post">
 
           {% csrf_token %}
@@ -42,6 +45,7 @@ <h1 class="ui medium header">
           {% block wizard_actions %}
             <div>
               {% if wizard.steps.prev %}
+                {# TODO: the previous button should not validate the form #}
                 <button class="ui button" name="wizard_goto_step" type="submit" value="{{ wizard.steps.prev }}">
                   {% trans "Previous" %}
                 </button>
@@ -56,15 +60,17 @@ <h1 class="ui medium header">
           {% endblock wizard_actions %}
 
         </form>
-      {% endblock project_add_content %}
-    </div>
+      </div>
+    {% endblock project_add_content %}
 
+    {% block project_add_help_topics %}
     <div class="ui ten wide tablet four wide computer column">
       <h2 class="ui small header">{% trans "Help topics" %}</h2>
       <div data-bind="using: EmbedTopicsView('intro/import-guide')">
         <div data-bind="template: { name: 'doc-topics' }"></div>
       </div>
     </div>
+    {% endblock project_add_help_topics %}
   </div>
 
   {% include "includes/utils/embed_docs.html" %}

readthedocsext/theme/templates/projects/import_config.html

@@ -0,0 +1,61 @@
+{% extends "projects/import_base.html" %}
+{% load i18n %}
+
+{% block project_add_content_subheader %}
+{% trans "Add a configuration file (<code>.readthedocs.yaml</code>) to your project" %}
+{% endblock project_add_content_subheader %}
+
+{% block project_add_css_classes %}ui ten wide tablet wide computer column{% endblock project_add_css_classes %}
+{% block project_add_content_main %}
+<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 class="ui padded">
+        <code class="ui small text">
+# .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 project_add_content_main %}
+
+{% block project_add_help_topics %}
+{% endblock project_add_help_topics %}