Post: "Builds with no index.html file" (#230)

* Post: "Builds with no `index.html` file"

Minimal changelog post announcing readthedocs/readthedocs.org#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.

* References :(

* Update with the content from the reviewed email

* Change date

Author: humitos

build-errors-docutils-0-18.rst

@@ -112,7 +112,7 @@ If you still experience problems, feel free to
 `open an issue <https://github.com/readthedocs/readthedocs.org/issues/>`_.
 
 .. 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 <readthedocs:config-file/v2:python.install>`

builds-without-index.rst

@@ -0,0 +1,24 @@
+.. post:: July 25, 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 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.
+
+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**.
+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 <readthedocs:tutorial/index>` to set up your project correctly.
+
+Please, `contact us`_ and let us know any inconvenient you may have with this change.
+
+.. _contact us: mailto:[email protected]

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.
 
 

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 <https://docs.readthedocs.io/page/config-file/v2.html#build-tools>`__ for more info.
 - 📚️ A new documentation how-to for ``.readthedocs.yaml`` was started at `Write the Docs <https://www.writethedocs.org/>`__ 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.