Read the Docs newsletter - December 2022

2022-12-06T00:00:00+00:00

This newsletter contains the first features and updates that have hatched since we announced a Q4 focus on core platform features in the previous newsletter.

News and updates

Here are the latest updates from our team:

⚙️ The entire build process can now be overridden (if you need it). See the Announcement.
- 💡️ This is useful if you want to publish outputs generated from a framework that isn’t supported by default. We wrote some examples for Pelican and Docsify.
- 💡️ You can also extend the build process for instance you can skip a build.
🐘️ We started tooting in the Fediverse (Mastodon). Follow us at @readthedocs@fosstodon.org
🛳️ Server-Side Search API v3 has been released.
🎬️ We are preparing to redirect our existing front pages to our new marketing site: about.readthedocs.com. Let us know know if you have comments or ideas for it.
⏳️ We organized a large refactor of our user documentation to comply with the Diátaxis methodology framework. So far, we broke it down into 73 tasks and counting.
✅️ We added a Unofficial and unmaintained projects policy that will help official maintainers to de-list forks among others.
✅️ We added an additional auditing feature, whereby invitations are added to the Security Log. The feature is available for users of Read the Docs for Business.
✅️ We found, fixed and disclosed a security issue, XSS: Allow serving of arbitrary HTML files from main domain.

You can always see the latest changes to our platforms in our Read the Docs Changelog.

Upcoming features

We’re working on improving our integration with Material for MkDocs, which is a great theme for MkDocs documentation projects.
Many improvements to our URL handling code, which will allow us to support more flexible URL configurations for projects.
A search redesign to make it nicer across our dashboard and in-doc search experiences.
404 pages are being improved by contextualization the user message, giving relevant guidance to readers and project owners.

Possible issues

Sphinx 6 is coming very soon. For those of you planning to upgrade immediately, we are preparing a blog post with a couple of considerations in that regard.

If you find regressions in any new releases of the sphinx-rtd-theme, please don’t hesitate to open an issue on GitHub.

Our Q4 focus also includes deprecating old and outdated approaches to using our platform. We don’t have anything firm to announce here yet, but we do plan to be more active in removing these features in the coming months.

Tip of the month

Do you need to document past or upcoming events? Chris Sewell has created sphinx-timeline for exactly this.

See sphinx-timeline in full action on the main page of AiiDA (which by the way is built with Read the Docs).

Awesome Project of the month

Nautobot is a great example of a documentation landing page with several subprojects. See all the highlights in the following Twitter thread:

Nautobot is the project of our today’s 💫 Showcase the Docs 🌟 edition!

“An extensible and flexible Network Source of Truth and Network Automation Platform that is the cornerstone of any network automation architecture” #Nautobot #documentation pic.twitter.com/icp2q2Epty
— Read the Docs (@readthedocs) November 22, 2022

Awesome Read the Docs Projects List 🕶️

Looking for more inspiration? Check out our new list: Awesome Read the Docs Projects.

Considering using Read the Docs for your next documentation project? Check out our documentation to get started!

Questions? Comments? Ideas for the next newsletter? Contact us!

Read the Docs Blog - Posted in 2022