diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst new file mode 100644 index 00000000..98c784d4 --- /dev/null +++ b/newsletter-november-2022.rst @@ -0,0 +1,99 @@ +.. post:: Nov 7, 2022 + :tags: newsletter, python + :author: Ben + :location: MLM + +.. meta:: + :description lang=en: + Company updates and new features from the last month, + current focus, and upcoming features. + +Read the Docs newsletter - November 2022 +======================================== + +Here are the first features and updates that have hatched since we announced a Q4 focus on core platform features in the :doc:`previous newsletter `. + + +New features +------------ + +The latest updates from our team: + +- :doc:`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 :doc:`Read the Docs Changelog `. + + +Upcoming features +----------------- + +- A 1.2.0 release of :ref:`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. + + +.. _november2022_tip_of_the_month + +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`_! + +.. Keeping this here for now, in case we need to link to ourselves :) + +.. _Contact us: mailto:hello@readthedocs.org diff --git a/theme-release-110.rst b/theme-release-110.rst index b39e0003..1f8ef0f6 100644 --- a/theme-release-110.rst +++ b/theme-release-110.rst @@ -60,6 +60,8 @@ If you have a project on Read the Docs without a Python requirements file ``requ You can read more about adding a ``requirements.txt`` in our :doc:`Documentation about Reproducible Builds `. +.. _sphinx_rtd_theme110_upcoming_releases: + Upcoming releases -----------------