From 1fcb0b33bca233b8b4a20ca9a2cdb50926405497 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 27 Oct 2022 16:58:57 +0200 Subject: [PATCH 1/8] Newsletter of November 2022 open for contribution --- newsletter-november-2022.rst | 67 ++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 newsletter-november-2022.rst diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst new file mode 100644 index 00000000..096298c3 --- /dev/null +++ b/newsletter-november-2022.rst @@ -0,0 +1,67 @@ +.. post:: Nov 1, 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 +======================================== + +A bunch of new features and updates have emerged 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. +- After rolling out auto-cancelling builds `last month `_, we have alread 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 `_ which themes and extensions that need jQuery will have to add as a dependency once Sphinx 6 is released. + +You can always see the latest changes to our platforms in our :doc:`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 page contextualization + + +Possible issues +--------------- + +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 +---------------- + +TBD + + +Project of the month +-------------------- + +TBD + +---- + +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 From 8620a3e58670a317f095d74fb4687c4209a7612a Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 4 Nov 2022 16:28:18 +0100 Subject: [PATCH 2/8] Updates the newsletter, adding Wagtail and a link to the new Awesome List --- newsletter-november-2022.rst | 43 +++++++++++++++++++++++++++++------- theme-release-110.rst | 2 ++ 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index 096298c3..a9df2cb0 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -11,7 +11,7 @@ Read the Docs newsletter - November 2022 ======================================== -A bunch of new features and updates have emerged since we announced a Q4 focus on core platform features in the :doc:`previous newsletter `. +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 @@ -19,26 +19,31 @@ New features The latest updates from our team: -- :doc:`sphinx-rtd-theme 1.1.0 ` has been released. -- After rolling out auto-cancelling builds `last month `_, we have alread recorded a whopping 10% decrease in builds. +- :doc:`sphinx-rtd-theme 1.1.0 ` has been released with minor improvements and as a step towards more development in the near future. +- 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 `_ which themes and extensions that need jQuery will have to add as a dependency once Sphinx 6 is released. +- 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 onewards. Sphinx 6.0 is scheduled for December 2022. You can always see the latest changes to our platforms in our :doc:`Read the Docs Changelog `. + Upcoming features ----------------- +- Soon, 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 page contextualization +- 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. @@ -50,10 +55,32 @@ Tip of the month TBD -Project of the month --------------------- +Awesome Project of the month +---------------------------- -TBD +`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 List πŸ•ΆοΈ +--------------- + +Looking for more inspiration? Check out our new list: `Awesome Read the Docs Projects `_. ---- 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 ----------------- From 1168c1bc9473d7d1d2c7be8a6e160b959e4a7343 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 4 Nov 2022 17:19:16 +0100 Subject: [PATCH 3/8] Adds Tip of the Month --- newsletter-november-2022.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index a9df2cb0..27bbc068 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -19,11 +19,11 @@ New features The latest updates from our team: -- :doc:`sphinx-rtd-theme 1.1.0 ` has been released with minor improvements and as a step towards more development in the near future. +- :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 onewards. Sphinx 6.0 is scheduled for December 2022. +- 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 onewards. 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 `. @@ -31,7 +31,7 @@ You can always see the latest changes to our platforms in our :doc:`Read the Doc Upcoming features ----------------- -- Soon, a 1.2.0 release of :ref:`sphinx-rtd-theme ` will support docutils 0.18 and Sphinx 6. +- 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. @@ -52,15 +52,18 @@ but we do plan to be more active in removing these features in the coming months Tip of the month ---------------- -TBD +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. 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... +`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 From 5f97005162eba102e8e721decce30d7b59dfb889 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Mon, 7 Nov 2022 13:54:18 +0100 Subject: [PATCH 4/8] Update newsletter-november-2022.rst Co-authored-by: Manuel Kaufmann --- newsletter-november-2022.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index 27bbc068..e02e1c97 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -52,7 +52,7 @@ 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: +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. 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. From 9c6d1b2e8934dd5466b2c8f2a1456af8a6a3b26c Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Mon, 7 Nov 2022 13:54:56 +0100 Subject: [PATCH 5/8] Update newsletter-november-2022.rst Co-authored-by: Manuel Kaufmann --- newsletter-november-2022.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index e02e1c97..d70fdf72 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -54,7 +54,7 @@ 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. In other words, it helps you make sure that your documentation's code examples look great. +- `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 πŸ‘‹ From 189fc0cab32106bb4ab10d9adf49b967762b4679 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Mon, 7 Nov 2022 21:45:24 +0100 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> Co-authored-by: Manuel Kaufmann --- newsletter-november-2022.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index d70fdf72..a57420b2 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -1,4 +1,4 @@ -.. post:: Nov 1, 2022 +.. post:: Nov 8, 2022 :tags: newsletter, python :author: Ben :location: MLM @@ -80,7 +80,7 @@ Personas πŸ‘©πŸ½β€πŸ’»β€‹: 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 List πŸ•ΆοΈ +Awesome Read the Docs Projects List πŸ•ΆοΈ --------------- Looking for more inspiration? Check out our new list: `Awesome Read the Docs Projects `_. From 2cac96f858ad67b9212af46eabac4640870d6a17 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Mon, 7 Nov 2022 22:03:20 +0100 Subject: [PATCH 7/8] Add a label for tip of the month, forward-bump date to today --- newsletter-november-2022.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index a57420b2..41e0f15a 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -1,4 +1,4 @@ -.. post:: Nov 8, 2022 +.. post:: Nov 7, 2022 :tags: newsletter, python :author: Ben :location: MLM @@ -49,6 +49,8 @@ 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 ---------------- @@ -81,7 +83,7 @@ Personas πŸ‘©πŸ½β€πŸ’»β€‹: 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 `_. From 1f1b25b1d1812b56e9f07bdc917ae3239fdebffa Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Mon, 7 Nov 2022 22:12:43 +0100 Subject: [PATCH 8/8] Fix a typo --- newsletter-november-2022.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index 41e0f15a..98c784d4 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -23,7 +23,7 @@ The latest updates from our team: - 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 onewards. Sphinx 6.0 is scheduled for December 2022 and will no longer bundle jQuery. +- 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 `.