Recent posts¶

• 05 September - Read the Docs newsletter - September 2023

  🚀 We started testing a new flyout menu as part of our beta test for documentation addons. The beta test is currently limited to projects using the build.commands configuration key.

  🛣️ We continue to have a number deprecations in progress. We announced this month deprecations of installing using system packages, the configuration key build.image, and installation of pinned versions of Sphinx and MkDocs. Keep an eye on your email for any deprecation notifications, as we will continue to notify maintainers of projects that might be impacted.

• 31 August - Addons flyout menu beta

  We are happy to announce that a new flyout menu is now available as part of the ongoing beta test for our latest project, Read the Docs Addons.

  After much hard work, we are excited to begin testing this feature with more projects. We have previously been testing other documentation features as part of this ongoing beta, but the flyout menu is by far the most prominent feature yet.

• 24 August - Enabling latest versions for Sphinx & Mkdocs builds

  We are announcing the deprecation of building with older documentation tool versions by default.

  Historically, Read the Docs installed a specific version 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.

• 09 August - Use build.os instead of build.image on your configuration file

  We are announcing the deprecation of build.image config key in favor of build.os. Read the Docs will start requiring a build.os config key for all projects in order to build documentation successfully. We will start failing builds for projects not using “build.os” in their config file on October 16, 2023.

  We understand this change will affect many of our users, so we have a timeline to communicate this deprecation to our users effectively.

• 08 August - Drop support for “Use system packages”

  Read the Docs used to pre-install common scientific Python packages like scipy, numpy, pandas, matplotlib and others at system level to speed up the build process. However, with all the work done in the Python ecosystem and the introduction of “wheels”, these packages are a lot easier to install via pip install and these pre-installed packages are not required anymore. If you have Apt package dependencies, they can be installed with build.apt_packages.

  With the introduction of our new “Ubuntu 20.04” and “Ubuntu 22.04” Docker images, we stopped pre-installing these extra Python packages and we encouraged users to install and pin all their dependencies using a requirements.txt file. We have already stopped supporting “use system packages” on these newer images.

• 03 August - Read the Docs newsletter - August 2023

  🏝️ A few team members took vacations this month, and everything kept running smoothly, which is always wonderful to see.

  ⏩ Our git cloning code was refactored, and now projects should be building much faster. The more git branches and tags you have, the faster the build will be.

• 25 July - 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.

• 12 July - Doctools without configuration file (conf.py / mkdocs.yml) are deprecated

  Historically Read the Docs has created a conf.py file for Sphinx projects and a mkdocs.yml file for MkDocs projects that don’t provide one, to make onboarding easier. This has been confusing a lot our users in different ways and we will remove the auto-creation of a default Sphinx/MkDocs configuration file for projects that don’t have one on August 28th. To avoid unexpected behavior or your documentation builds failing, you should add a configuration file to your project by this date.

  The auto-creation of a default configuration file will be completely removed on August 28th. Add a conf.py/mkdocs.yml to your projects before this date to avoid unexpected build failures.

• 10 July - Support for PyPy3 removed

  Starting on July 18, 2023 PyPy3 will be removed as an option to build documentation on Read the Docs.

  This feature was introduced as an alternative to make Sphinx build faster. However, we found there are no projects building their documentation with PyPy3 and we decided to remove its support to simplify our product and reduce development maintanence.

• 10 July - Python “core requirements” for new projects will install latest version

  Starting on August 7, 2023 all new projects imported on Read the Docs will install only sphinx, mkdocs and readthedocs-sphinx-ext as “core requirements”. The default behavior will be to install the latest version of these requirements.

  Note that previously Read the Docs was installing also jinja, sphinx-rtd-theme, pillow, mock, alabaster, commonmark and recommonmark specifying particular versions depending on different factors that were confusing for users and hard to debug.