Docs: Add some messages flagging the upcoming requirement of a .readt…

…hedocs.yaml (#10389) * Add some messages flagging the upcoming requirement of a .readthedocs.yaml * Update docs/user/config-file/v1.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Add more guidance * warning box => paragraph text, rename section * Update docs/user/tutorial/index.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Hello darken my old friend, I've come to speak with you again --------- Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
readthedocs · Jun 8, 2023 · a9dc303 · a9dc303
1 parent 60b4133
commit a9dc303
Show file tree

Hide file tree

Showing 4 changed files with 25 additions and 9 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -102,6 +102,7 @@
     "rst-to-myst": ("https://rst-to-myst.readthedocs.io/en/stable/", None),
     "rtd": ("https://docs.readthedocs.io/en/stable/", None),
     "rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
+    "rtd-blog": ("https://blog.readthedocs.com/", None),
     "jupyter": ("https://docs.jupyter.org/en/latest/", None),
 }
 

diff --git a/docs/user/config-file/v1.rst b/docs/user/config-file/v1.rst
@@ -8,8 +8,8 @@ Read the Docs has support for configuring builds with a YAML file.
 
 .. warning::
 
-   Version 1 is deprecated and shouldn't be used.
-   The version 2 of the configuration file is now available.
+   Version 1 is deprecated and :doc:`support will be removed in September 2023 <rtd-blog:migrate-configuration-v2>`.
+   You should use version 2 of the configuration file.
    See the :ref:`new features <config-file/v2:New settings>`
    and :ref:`how to migrate from v1 <config-file/v2:Migrating from v1>`.
 

diff --git a/docs/user/intro/import-guide.rst b/docs/user/intro/import-guide.rst
@@ -75,11 +75,16 @@ and the documentation will be built.
 Check out our :doc:`/builds` page to learn more about how Read the Docs builds your docs,
 and to troubleshoot any issues that arise.
 
-Some documentation projects require additional configuration to build
-such as specifying a certain version of Python or installing additional dependencies.
+We require an additional configuration file to build your project.
+This allows you to specifying special requirements for your build,
+such as your version of Python or how you wish to install addition Python requirements.
 You can configure these settings in a ``.readthedocs.yaml`` file.
 See our :doc:`/config-file/index` docs for more details.
 
+.. note::
+
+   Using a configuration file :doc:`is required from September 2023 <rtd-blog:migrate-configuration-v2>`.
+
 It is also important to note that the default version of Sphinx is ``v1.8.5``.
 We recommend to set the version your project uses :doc:`explicitily with pinned dependencies </guides/reproducible-builds>`.
 

diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst
@@ -284,8 +284,14 @@ you will access the build logs,
 otherwise it will take you directly to the documentation.
 When you are satisfied, you can merge the pull request!
 
-Customizing the build process
------------------------------
+Adding a configuration file
+---------------------------
+
+As of September 2023,
+:doc:`you will need to add a configuration file to build your documentation <rtd-blog:migrate-configuration-v2>`.
+Until then,
+this example project will build without the configuration file,
+but we **strongly recommend** completing this section in order to add a configuration file.
 
 The Settings page of the :term:`project home` allows you
 to change some *global* configuration values of your project.
@@ -297,9 +303,13 @@ This has several advantages:
 - It can be different for every version (more on versioning in the next section).
 - Some configurations are only available using the config file.
 
-Read the Docs works without this configuration
-by :ref:`making some decisions on your behalf <build-default-versions:Default versions of dependencies>`.
-For example, what Python version to use, how to install the requirements, and others.
+This configuration file should be part of your Git repository.
+It should be located in the base folder of the repository and be named ``.readthedocs.yaml``.
+
+.. TODO: We are adding a how-to that we need to include in this tutorial.
+.. Maybe by reference or maybe as full-featured content.
+
+In this section, we will show you some examples of what a configuration file should contain.
 
 .. tip::