diff --git a/docs/conf.py b/docs/conf.py index 5730680b173..e2747e4c4ad 100644 --- 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 index 9891aee8333..4ba483db1d6 100644 --- 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 `. + You should use version 2 of the configuration file. See the :ref:`new features ` and :ref:`how to migrate from v1 `. diff --git a/docs/user/intro/import-guide.rst b/docs/user/intro/import-guide.rst index d4b3bd2c7d5..32fbac07ca4 100644 --- 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 `. + 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 `. diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index bf76ee880f7..55af5deed97 100644 --- 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 `. +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 `. -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::