Posted in 2023
Read the Docs newsletter - September 2023
- 05 September 2023
- Spokane, Washington
- Newsletter
🚀 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.
Addons flyout menu beta
- 31 August 2023
- Barcelona, Spain
- Feature announcement
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.
Enabling latest versions for Sphinx & Mkdocs builds
- 24 August 2023
- Barcelona, Spain
- Changelog
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.
Use build.os instead of build.image on your configuration file
- 09 August 2023
- Barcelona, Spain
- Changelog
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.
Drop support for “Use system packages”
- 08 August 2023
- Barcelona, Spain
- Changelog
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.
Read the Docs newsletter - August 2023
- 03 August 2023
- Bend, Oregon
- Newsletter
🏝️ 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.
Builds with no index.html at its output’s directory are deprecated
- 25 July 2023
- Barcelona, Spain
- Changelog
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.
Doctools without configuration file (conf.py / mkdocs.yml) are deprecated
- 12 July 2023
- Barcelona, Spain
- Changelog
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.
Support for PyPy3 removed
- 10 July 2023
- Barcelona, Spain
- Changelog
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.
Python “core requirements” for new projects will install latest version
- 10 July 2023
- Barcelona, Spain
- Changelog
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.
Read the Docs newsletter - July 2023
- 06 July 2023
- Bend, Oregon
- Newsletter
🚀 We shipped support for customizing the URL path for projects and subprojects, allowing you to remove or customize the /projects/ path on subprojects. This is enabled via Support request currently, and only on certain plans on Read the Docs for Business.
🛣️ Deprecations underway:
We have a number of old feature deprecations underway.
The goal here is to reduce complexity of our build platform,
and enable users to control their own builds via build.tools
and build.commands
instead of feature flags.
Keep an eye on your email for any deprecation notifications that might impact your project.
Read the Docs newsletter - June 2023
- 05 June 2023
- Malmö, Sweden
- Newsletter
⚠️ A .readthedocs.yaml
configuration file will be required for your future builds.
Read more about this change in Migrate your project to .readthedocs.yaml configuration file v2.
✅️ Visiting a language slug of a project without specifying the version now redirects to the default version.
For instance, /en/
redirects to /en/latest/
.
Migrate your project to .readthedocs.yaml configuration file v2
- 31 May 2023
- Barcelona, Spain
- Changelog
We are announcing a new requirement for all builds to use our configuration file version 2. This announcement deprecates builds without a configuration file, as well as version 1 of our configuration file.
Read the Docs will start requiring a .readthedocs.yaml
configuration file
for all projects in order to build documentation successfully.
We will stop supporting builds without explicit configuration,
because this creates implicit dependencies that users aren’t aware of.
We plan to start failing builds not using configuration file version 2 on September 25, 2023.
Read the Docs newsletter - May 2023
- 11 May 2023
- Malmö, Sweden
- Newsletter
🚁️ The proxy application El Proxito has been rewritten. El Proxito resolves URLs for all documentation websites hosted on Read the Docs. The new rewrite improves the performance of the resolver and makes it possible to add planned features.
🔎️ …One of the new features available in the new El Proxito implementation, is an improved 404 page (see the screenshot below). The new 404 page is contextualized and contains better error messages and tips for users and project owners. We are gradually rolling out the new El Proxito while monitoring its stability, and users will experience new features only on projects where it has been enabled.
Read the Docs newsletter - April 2023
- 07 April 2023
- Malmö, Sweden
- Newsletter
📚️ Over the past ~6 months, we gradually refactored our user documentation to align with the Diátaxis Framework. The results are now manifested in the structure of the navigation sidebar and the landing page on docs.readthedocs.io.
📊️ All of our websites now use Plausible for analytics.
Read the Docs website migration to about.readthedocs.com
- 09 March 2023
- Portland, Oregon
- Changelog
Read the Docs is in the process of migrating our primary marketing website to a single site: https://about.readthedocs.com. The new site offers users more information about our products and their features, in a combined presentation of what was previously divided between two websites (Read the Docs Community (readthedocs.org) and Read the Docs for Business (readthedocs.com)). The new site will also serve as a single entrypoint for users that are logging in to Read the Docs accounts. There has been a good deal of confusion around our two sites, and this change makes it more clear which site you’re going to.
Importantly, we are keeping both our Community and Business sites separate for logged in users. There are no changes in our commitment to offering free hosting for open source, or the separation of infrastructure for Business customers.
Read the Docs newsletter - March 2023
- 07 March 2023
- Malmö, Sweden
- Newsletter
⭐️ We passed our 10,000th issue/pull request on GitHub. And it’s pretty much an equal split between the 5039 issues and 4872 pull requests now registered. Thanks to the whole community for building this together through code, issues, suggestions… and documentation!
🌪️ Follow up: Build times have gone rapidly down after last month’s introduction of parallel uploading of artifacts with rclone. Depending on the number of files in your build output, build times may have gone down several seconds or several minutes. For instance, a large project like Write the Docs has gone down from ~7 minutes to under 3 minutes. If you want to see the change for your project, have a look at your build times before and after February 8.
Read the Docs newsletter - February 2023
- 07 February 2023
- Malmö, Sweden
- Newsletter
Here are the latest updates from our team since the previous newsletter:
🪄️ Build outputs are now stored in a well-known location: _readthedocs/<format>
.
This opens up many new and exciting possibilities for generating and processing final output formats,
which we will uncover in an upcoming blog post.
PDFs for MkDocs and encrypted documentation are just two demos that we have ready.
Stay tuned!
Read the Docs newsletter - January 2023
- 10 January 2023
- Malmö, Sweden
- Newsletter
Happy 2023!
Here are the latest updates from our team since the previous newsletter:
Sphinx 6 is out and has important breaking changes
- 04 January 2023
- Malmö, Sweden
Important updates to this post ⬇️
sphinx-rtd-theme 1.2.0 has been released with support for Sphinx 6.