Update blog post for default dependencies (#243)

This tries to clarify a few points:

- We have altered more dependencies than just Sphinx/Mkdocs
- Explain the actual changes to dependencies a bit clearer and more explicitly
- Mention some of the errors that are possible so that search can pick up on this

Author: agjohnson

defaulting-latest-build-tools.rst

@@ -4,31 +4,75 @@
    :location: BCN
    :category: Changelog
 
-Enabling latest versions for Sphinx & Mkdocs builds
-===================================================
+Changes to default project dependencies
+=======================================
 
-We are announcing the deprecation of building with older documentation tool versions by default.
+.. note::
 
-Historically, Read the Docs installed a specific version based on the date your project was created.
+   This post was updated on Oct 10 to reflect all of the changes to installed dependencies
+
+We are announcing the deprecation of automatic installation of several key project dependencies,
+and builds will no longer install older documentation tool versions by default.
+
+Historically, Read the Docs installed a specific version of several dependencies based on the date your project was created.
 This caused odd issues where reimporting a project could change behavior, and caused users to continue using very old versions of build tools that weren't supported by their authors.
 This was done to maintain backwards compatibility,
 but our platform now has robust support for defining a build environment,
 so we encourage you to pin your dependencies instead.
 
-**Starting on October 3rd Read the Docs will install the latest available version of MkDocs and Sphinx by default**.
-We are also not going to be installing other build dependencies, like ``mock`` and ``recommonmark``.
-If you want to use a different version, you can do this by pinning your dependencies.
+**Starting on October 3rd default dependencies installed for each project build will change.**
+If your project was previously depending on these default dependencies,
+your project's builds may encounter errors or failures due to missing packages.
+
+To resolve these build failures we recommend defining all of your project's dependencies.
+See the examples below for guidance on how to update your project configuration
+or learn more about managing dependencies in our `guide for reproducible builds <https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html>`_.
+
+The changes to default dependencies installed during the build process are:
+
+.. list-table::
+   :header-rows: 1
+   :width: 100%
+   :align: center
+   :widths: 10, 5, 5
+
+   - * Package
+     * Prior version
+     * New version
+   - * Sphinx
+     * ``1.8.5``
+     * *Latest release*
+   - * MkDocs
+     * ``0.17.3``
+     * *Latest release*
+   - * ``sphinx-rtd-theme``
+     * *Latest release*
+     * *Not installed*
+   - * ``recommonmark``
+     * *Latest release*
+     * *Not installed*
+   - * ``commonmark``
+     * *Latest release*
+     * *Not installed*
+   - * ``pillow``
+     * *Latest release*
+     * *Not installed*
+   - * ``mock``
+     * *Latest release*
+     * *Not installed*
 
 Sphinx example
 --------------
 
-Previously we were installing ``Sphinx 1.8``,
-which is no longer supported.
-You should pin a specific version so that your documentation builds are reproducible.
+If your project uses Sphinx to build its documentation,
+you will need to install Sphinx and may need to install the ``sphinx-rtd-theme`` package.
+Previously, Sphinx version ``1.8.5`` could have been the default version installed for your project,
+which we do not recommend installing as it is no longer supported.
 
-Example ``.readthedocs.yaml`` configuration file:
+A basic configuration example to work from would include the following files:
 
 .. code-block:: yaml
+  :caption: .readthedocs.yaml
 
   version: 2
 
@@ -42,7 +86,8 @@ Example ``.readthedocs.yaml`` configuration file:
      install:
        - requirements: docs/requirements.txt
 
-The content of ``docs/requirements.txt`` would be similar to::
+.. code-block::
+  :caption: docs/requirements.txt
 
   sphinx==6.2.1
   sphinx-rtd-theme==1.2.2
@@ -51,16 +96,16 @@ The content of ``docs/requirements.txt`` would be similar to::
   commonmark==0.9.1
   recommonmark==0.5.0
 
-Mkdocs example
+MkDocs example
 --------------
 
-Previously we were installing ``Mkdocs 0.17.3``,
-which is no longer supported.
-You should pin a specific version so that your documentation builds are reproducible.
+If your project uses MkDocs to build its documentation,
+you will need to find the latest version of MkDocs that your project can use.
 
-Example ``.readthedocs.yaml`` configuration file:
+A basic configuration example to work from would include the following files:
 
 .. code-block:: yaml
+  :caption: .readthedocs.yaml
 
   version: 2
 
@@ -74,14 +119,23 @@ Example ``.readthedocs.yaml`` configuration file:
      install:
        - requirements: docs/requirements.txt
 
-The content of ``docs/requirements.txt`` would be similar to::
+.. code-block::
+  :caption: docs/requirements.txt
 
   mkdocs==1.5.1
 
-Reproducible builds
--------------------
 
-We highly recommend pinning your dependencies so that you can ensure a working build environment across time and on different build servers.
+.. This section is mostly to direct search results
+
+Build errors
+------------
+
+Some of the errors you might encounter are from missing dependencies:
+
+- ``ModuleNotFoundError: No module named 'sphinx_rtd_theme'``
+- ``ModuleNotFoundError: No module named 'recommonmark'``
 
-You can learn more about this in our `reproducible builds <https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html>`_ guide.
+Or you might notice errors from backwards incompatible API changes on modern
+releases of Sphinx, ``docutils``, and other packages:
 
+- ``AttributeError: 'Module' object has no attribute 'doc'``