Promote the YAML config

docs/config-file/v2.rst

@@ -4,25 +4,40 @@ Configuration File V2
 Read the Docs supports configuring your documentation builds with a YAML file.
 :doc:`The Read the Docs file <index>` must be in the root directory of your project.
 
-Here is an example of how this file looks like:
+Below is an example YAML file which may require some changes for your project's configuration:
 
 .. code:: yaml
 
-   # .readthedocs.yml
+    # .readthedocs.yml
+    # Read the Docs configuration file
+    # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-   version: 2
+    # Required
+    version: 2
+
+    # Build documentation in the docs/ directory with Sphinx
+    sphinx:
+      configuration: docs/conf.py
+
+    # Build documentation with MkDocs
+    #mkdocs:
+    #  configuration: mkdocs.yml
+
+    # Optionally build your docs in additional formats such as PDF and ePub
+    formats: all
+
+    # Optionally set the version of Python and requirements required to build your docs
+    python:
+      version: 3.7
+      install:
+        - requirements: docs/requirements.txt
 
-   python:
-     version: 3.7
-     install:
-        - method: pip
-          path: .
 
 Supported settings
 ------------------
 
 .. note::
-   
+
    The presence of any other key that isn't documented here will make the build to fail.
    This is to avoid typos and provide feedback on invalid configurations.
 
@@ -34,11 +49,11 @@ version
 Example:
 
 .. code-block:: yaml
-   
+
    version: 2
 
 .. warning::
-   
+
    If you don't provide the version, :doc:`v1 <v1>` will be used.
 
 formats
@@ -329,13 +344,13 @@ VCS submodules configuration.
    Only Git is supported at the moment.
 
 .. note::
-   
+
    You can't use ``include`` and ``exclude`` settings for submodules at the same time.
 
 Example:
 
 .. code-block:: yaml
-   
+
    submodules:
      include:
         - one
@@ -351,7 +366,7 @@ List of submodules to be included.
 :Default: ``[]``
 
 .. note::
-   
+
    You can use the ``all`` keyword to include all submodules.
 
    .. code-block:: yaml
@@ -368,7 +383,7 @@ List of submodules to be excluded.
 :Default: ``[]``
 
 .. note::
-   
+
    You can use the ``all`` keyword to exclude all submodules.
    This is the same as ``include: []``.
 

readthedocs/templates/projects/import_basics.html

@@ -6,10 +6,9 @@ <h3>{% trans "Project Details" %}</h3>
 
   <p class="info">
     {% blocktrans trimmed %}
-      To import a project,
-      start by entering a few details about your repository.
-      More advanced project options can be configured
-      if you select <b>Edit advanced project options</b>.
+      To import a project, start by entering a few details about your repository.
+      You can set additional configuration options for your documentation in a
+      <a href="https://docs.readthedocs.io/en/stable/config-file/v2.html">.readthedocs.yml</a> file.
     {% endblocktrans %}
   </p>