From 60f8539bc687381c5e9ea565c224ee979c16bb01 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 19 Jul 2023 13:13:30 +0200 Subject: [PATCH 1/4] Post: "Builds with no `index.html` file" Minimal changelog post announcing https://github.com/readthedocs/readthedocs.org/issues/1800 Currently, we are logging this projects, but on August 1st we will be failing builds that do not generate an `index.html` on the output's directory. --- builds-without-index.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 builds-without-index.rst diff --git a/builds-without-index.rst b/builds-without-index.rst new file mode 100644 index 0000000..052dfab --- /dev/null +++ b/builds-without-index.rst @@ -0,0 +1,27 @@ +.. post:: July 20, 2023 + :tags: builders + :author: Manuel + :location: BCN + :category: Changelog + +Builds with no ``index.html`` at its output's directory are deprecated +====================================================================== + +Historically, Read the Docs has created an auto-generated ``index.html`` file with minimal instructions about how to setup the project correctly +for those builds that weren't outputting this file. +This auto-generated file has confused more users than helped them. +Mainly, because the behavior on Read the Docs was different from the behavior on their local environment. + +Due to this, we decided to stop creating the ``index.html`` file automatically. +Besides, we will check for an ``index.html`` file at the end of the build, +and fail it with a clear message of the problem if there is no ``index.html`` file in the ``$READTHEDOCS_OUTPUT/html`` directory. +This will help users to immediately understand what's the problem and how to solve it. + +Builds from projects that are not generating an ``index.html`` file **will start to fail on August 1st at ~9AM PST**, after our regular deploy. +Make sure your project is properly configured and it's creating an ``index.html`` file before that date to avoid unexpected behaviors. + +We recommend you following our :doc:`tutorial ` to set up your project correctly. + +Please, `contact us`_ and let us know any inconvenient you may have with this change. + +.. _contact us: mailto:hello@readthedocs.org From 5078afb1af7386affd3a8c38f29e931853793f69 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 20 Jul 2023 11:34:13 +0200 Subject: [PATCH 2/4] References :( --- build-errors-docutils-0-18.rst | 2 +- builds-without-index.rst | 2 +- migrate-configuration-v2.rst | 2 +- newsletter-july-2023.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/build-errors-docutils-0-18.rst b/build-errors-docutils-0-18.rst index b3843c9..9f3db52 100644 --- a/build-errors-docutils-0-18.rst +++ b/build-errors-docutils-0-18.rst @@ -112,7 +112,7 @@ If you still experience problems, feel free to `open an issue `_. .. seealso:: - :doc:`readthedocs:guides/setup/configuration-file` + :doc:`readthedocs:config-file/index` An introduction to our configuration file and some basic usage examples :ref:`.readthedocs.yaml python.install options ` diff --git a/builds-without-index.rst b/builds-without-index.rst index 052dfab..4d1f8ac 100644 --- a/builds-without-index.rst +++ b/builds-without-index.rst @@ -20,7 +20,7 @@ This will help users to immediately understand what's the problem and how to sol Builds from projects that are not generating an ``index.html`` file **will start to fail on August 1st at ~9AM PST**, after our regular deploy. Make sure your project is properly configured and it's creating an ``index.html`` file before that date to avoid unexpected behaviors. -We recommend you following our :doc:`tutorial ` to set up your project correctly. +We recommend you following our :doc:`tutorial ` to set up your project correctly. Please, `contact us`_ and let us know any inconvenient you may have with this change. diff --git a/migrate-configuration-v2.rst b/migrate-configuration-v2.rst index acd5703..72682e3 100644 --- a/migrate-configuration-v2.rst +++ b/migrate-configuration-v2.rst @@ -122,7 +122,7 @@ you should be able to define a working configuration file and avoid breaking cha .. seealso:: - :doc:`readthedocs:guides/setup/configuration-file` + :doc:`readthedocs:config-file/index` More usage examples and guidance can be found in our how-to for adding a ``.readthedocs.yaml`` configuration file. diff --git a/newsletter-july-2023.rst b/newsletter-july-2023.rst index 8eb3528..07d8253 100644 --- a/newsletter-july-2023.rst +++ b/newsletter-july-2023.rst @@ -26,7 +26,7 @@ News and updates including the latest stable versions of Python, PyPy, Node.js, Rust and Go. See the documentation of the `build.tools `__ for more info. - 📚️ A new documentation how-to for ``.readthedocs.yaml`` was started at `Write the Docs `__ and finished recently. - Read it here: :doc:`readthedocs:guides/setup/configuration-file`. + Read it here: :doc:`readthedocs:config-file/index`. - ⏩️ HTTP speedups: Several HTTP endpoints and CloudFlare configurations have been tweaked and are performing better. - 🐛️ Bug fix: We are now 100% relying on search indexing by parsing HTML, instead of special Sphinx-only logic. This makes search a lot simpler and more consistent for our users. From 9bad5c2768eb366210d1faf5e228ea430a23dd48 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 20 Jul 2023 11:36:54 +0200 Subject: [PATCH 3/4] Update with the content from the reviewed email --- builds-without-index.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/builds-without-index.rst b/builds-without-index.rst index 4d1f8ac..e6aea5c 100644 --- a/builds-without-index.rst +++ b/builds-without-index.rst @@ -7,18 +7,15 @@ Builds with no ``index.html`` at its output's directory are deprecated ====================================================================== -Historically, Read the Docs has created an auto-generated ``index.html`` file with minimal instructions about how to setup the project correctly -for those builds that weren't outputting this file. -This auto-generated file has confused more users than helped them. -Mainly, because the behavior on Read the Docs was different from the behavior on their local environment. +Historically, Read the Docs has created an auto-generated ``index.html`` file with minimal instructions about how to setup the project correctly when your build didn’t output this file. +This auto-generated file has confused more users than it has helped because the behavior on Read the Docs was different from the behavior on their local environment. -Due to this, we decided to stop creating the ``index.html`` file automatically. -Besides, we will check for an ``index.html`` file at the end of the build, -and fail it with a clear message of the problem if there is no ``index.html`` file in the ``$READTHEDOCS_OUTPUT/html`` directory. -This will help users to immediately understand what's the problem and how to solve it. +To better onboard users, we have deprecated the auto-creation of ``index.html`` files on Read the Docs projects. +We will now check for an ``index.html`` file at the end of the build, +and fail it with a clear message of the problem if there is no ``index.html`` file in the top level of your output directory. -Builds from projects that are not generating an ``index.html`` file **will start to fail on August 1st at ~9AM PST**, after our regular deploy. -Make sure your project is properly configured and it's creating an ``index.html`` file before that date to avoid unexpected behaviors. +Builds from projects that are not generating an ``index.html`` file **will start to fail on August 1st**. +Make sure your project is properly configured and it’s creating an ``index.html`` file before that date to avoid unexpected behaviors. We recommend you following our :doc:`tutorial ` to set up your project correctly. From 3ce1cfdfc7a5d8da6cf11de4159a2d0fdc111573 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Jul 2023 10:44:19 +0200 Subject: [PATCH 4/4] Change date --- builds-without-index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builds-without-index.rst b/builds-without-index.rst index e6aea5c..6134e19 100644 --- a/builds-without-index.rst +++ b/builds-without-index.rst @@ -1,4 +1,4 @@ -.. post:: July 20, 2023 +.. post:: July 25, 2023 :tags: builders :author: Manuel :location: BCN