New features¶

The latest updates from our team:

• sphinx-rtd-theme 1.1.0 has been released with minor improvements and as a big step towards future releases with larger changes.

• After rolling out auto-cancelling builds last month, we have already recorded a whopping 10% decrease in builds. We’re really happy with how this turned out, not least that it effectively reduces our cloud footprint by 10% 🌱.

• We started incrementally refactoring our own documentation to match the Diátaxis framework. We will be writing more about this, as we are currently gaining practical experience.

• Much thanks to AA-Turner and the Sphinx community for working together on a proposal and releasing the extension sphinxcontrib-jquery. This extension is required for themes and extensions that need jQuery from Sphinx 6 and onward. Sphinx 6.0 is scheduled for December 2022 and will no longer bundle jQuery.

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

Upcoming features¶

• A 1.2.0 release of sphinx-rtd-theme will support docutils 0.18 and Sphinx 6.

• 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¶

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

We continue planning to be more active in deprecating old and outdated approaches to using our platform in Q4. 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¶

This tip of the month comes from our own experience. We have greatly benefitted from the following two Python/Django projects:

• blacken-docs is a pre-commit linter that checks and formats your Python code embedded in your documentation. In other words, it helps you make sure that your documentation’s code examples look great.

• django-upgrade saves us a lot of time each time we upgrade to the latest Django version.

As you might have noticed, both of these projects are maintained by Adam Johnson. Thanks, Adam 👋

Awesome Project of the month¶

As we also tweeted, we are really big fans of how the Wagtail community has built its documentation on docs.wagtail.org. Our favorite parts are…

Custom theme 🎨:

Wagtail uses a beautiful custom Sphinx theme with dark mode support

Release notes 🚢:

Its documentation includes carefully curated 💅​ release notes that developers are happy to read. They include what’s new, bug fixes, new features and upgrade notes between versions. Take a look at their latest major release notes.

Contribution guide 👩‍👩‍👧​👨‍👨‍👦‍👦​:

Wondering how to write a GOOD “Contribution guide” 👩‍👩‍👧​👨‍👨‍👦‍👦​👨‍👩‍👧‍👦​​? Take a look at Wagtail’s Contribution Guide. It gives a brief overview of how you can contribute and once you have decided what you want to do, you can read more in 11 carefully crafted categories.

Personas 👩🏽‍💻​:

Wagtail divides the readers in two categories: “developers 👩🏽‍💻​ that want to install and maintain their Wagtail instance” and “users👨‍💼 of a Wagtail-powered site”. This makes it easier for each of these two personas to find what they are looking for immediately.

5 out of 6 contributors write documentation 🎉 🎉 🎉:

Wagtail has a stunning amount of documentation contributors! Out of the ~600 contributors to Wagtail, ~500 of those have written documentation. Most of them added changelog entries or release notes, since adding code changes requires updating the changelog. This is a great way to potentially turn your code contributors into documentation contributors.

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!