From 3a6155b902545370e8ea906557cb58df48c87d76 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Mon, 5 Jun 2023 23:37:40 +0200 Subject: [PATCH 1/6] Add some messages flagging the upcoming requirement of a .readthedocs.yaml --- docs/conf.py | 1 + docs/user/config-file/v1.rst | 4 ++-- docs/user/intro/import-guide.rst | 9 +++++++-- docs/user/tutorial/index.rst | 6 ++++++ 4 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e547bd88425..7c7c4384824 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..3de4b374521 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 is removed in September 2023 `. + Instead, use the 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..c8ce8cb7004 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -287,6 +287,11 @@ When you are satisfied, you can merge the pull request! Customizing the build process ----------------------------- +.. warning:: + + We are updating this tutorial. + :doc:`As of September 2023, you need to add a configuration file as mentioned in these steps `. + The Settings page of the :term:`project home` allows you to change some *global* configuration values of your project. In addition, you can further customize the building process @@ -301,6 +306,7 @@ 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. + .. tip:: Settings that apply to the entire project are controlled in the web dashboard, From 2770dd6fdb0fd41cef6dab5a814346cbd8c8efec Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Mon, 5 Jun 2023 23:53:44 +0200 Subject: [PATCH 2/6] Update docs/user/config-file/v1.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/config-file/v1.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/config-file/v1.rst b/docs/user/config-file/v1.rst index 3de4b374521..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 :doc:`support is removed in September 2023 `. - Instead, use the version 2 of the configuration file. + 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 `. From 1791f222248a953142fc47f9d3f89fdbd81f7175 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 6 Jun 2023 00:11:15 +0200 Subject: [PATCH 3/6] Add more guidance --- docs/user/tutorial/index.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index c8ce8cb7004..7ce24662524 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -302,10 +302,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:: From 95ba2acadea9174fd2dfde2cb32822fb460bbb54 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 14:16:35 +0200 Subject: [PATCH 4/6] warning box => paragraph text, rename section --- docs/user/tutorial/index.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 7ce24662524..a52c7b19139 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -284,13 +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 ------------------------------ - -.. warning:: - - We are updating this tutorial. - :doc:`As of September 2023, you need to add a configuration file as mentioned in these steps `. +Adding a configuration file +--------------------------- + +We are currently updating this tutorial. +:doc:`As of September 2023, you need to add a configuration file as mentioned in these steps `. +Until then, +the tutorial's example project will build without the configuration file. +But we **highly** 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. From 51c485fcdcbcacbb4f64db72a524ffd23805af37 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Thu, 8 Jun 2023 00:10:10 +0200 Subject: [PATCH 5/6] Update docs/user/tutorial/index.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/tutorial/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index a52c7b19139..19daf600bd0 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -287,11 +287,11 @@ When you are satisfied, you can merge the pull request! Adding a configuration file --------------------------- -We are currently updating this tutorial. -:doc:`As of September 2023, you need to add a configuration file as mentioned in these steps `. +As of September 2023, +:doc:`you will need to add a configuration file to build your documentation `. Until then, -the tutorial's example project will build without the configuration file. -But we **highly** recommend completing this section in order to add a configuration file. +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. From 9d81092d27fdae06ca43ed6ad2513d7ecf070d39 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 8 Jun 2023 12:18:05 +0200 Subject: [PATCH 6/6] Hello darken my old friend, I've come to speak with you again --- docs/user/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 19daf600bd0..55af5deed97 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -287,7 +287,7 @@ When you are satisfied, you can merge the pull request! Adding a configuration file --------------------------- -As of September 2023, +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,