Read the Docs Blog - Posts tagged newsletter

Read the Docs newsletter - March 2022

2022-03-10T00:00:00Z

Read the Docs newsletter - February 2022

2022-02-08T00:00:00Z

Welcome to the latest edition of our monthly newsletter, where we share the most relevant updates around Read the Docs, offer a summary of new features we shipped during the previous month, and share what we’ll be focusing on in the near future.

Company updates

We have mostly finished migrating Read the Docs for Business users to Cloudflare for SSL. There are lots of interesting features this will enable, so stay tuned for updates there.
We’re sad to announce that Juan Luis has moved on from Read the Docs as our developer advocate. The work he did was vital towards getting our CZI grant mostly finished, and we thank him for his time spent bettering the RTD, Sphinx, and docs community.
On a related note, we’re going to be hiring again soon to fill another position. It will be a bit different and likely a product-focused Python development position. If you’re interested, please let us know.

New features

In January we continued to work on refactors and internal changes. Among the major user-facing changes:

We fixed a bug in Bitbucket that didn’t allow us to properly sync user permissions. This resulted in a few support requests, but has now been resolved.
We improved our ability to mark projects as non-spam, so that we can validate a project isn’t spam and then make sure it doesn’t get flagged by our automated system.

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

Upcoming features

Cancelling a build is a long requested feature, and we’re getting close to implementing it.
We’re looking at tracking 404 pages in our project analytics, so that projects can easily fix up missing or outdated page links.
We are hoping to launch our revamped landing pages this month, which will give our front page a much needed refresh.
We are working to define a policy for canonical docs and cloned versions, so that we can more easily remove outdated docs for projects.
We’re working to investigate supporting a CDN on Read the Docs for Business, which will be an exciting new feature for our users there.
We’re looking at how to support multiple readthedocs.yml files in a single git repo.

Possible issues

We continue to see a good pace of development on the Sphinx project, with them adding support for docutils 0.18, and removing jQuery in a major refactor of their Javascript. We’re working to ensure that our theme and other parts of the ecosystem don’t break with these changes, and trying to be procative to address any possible issues. That said, there will likely still be some issues that sneak through with the release of Sphinx 4.5 (docutils upgrade) and Sphinx 5.0 (JS refactor).

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

Read the Docs newsletter - January 2022

2022-01-12T00:00:00Z

Company highlights

We are now managing custom domains for our corporate users using Cloudflare SSL for SaaS, which will remove the manual work that was needed on our side and make the process of setting up a custom domain almost instantaneous. It also will allow us to offer a CDN much easier in the future.
We improved our spam classification system, and started blocking the dashboard on spammy projects. We are happy to report that the traffic to spammy projects has already reduced significantly.

New features

December and January have been slow months, and we mainly worked on internal changes and documentation improvements. Among the major user-facing changes:

We changed the Google Analytics from a persistent 30 day cookie to a session cookie that is deleted when the browser is closed. This will result in less data collected from users.
We split the developer documentation from the user documentation to avoid confusion and made our Read the Docs for Business docs more visible.
We expanded our user documentation with more examples on how to use MyST Markdown and a guide to migrate from reST to MyST (more about our committment to support MyST in our blog).

Thanks to our external contributor Çağatay Yiğit Şahin.

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

Upcoming features

Ana will continue working on the new landing pages, polishing the copywriting along with Juan Luis and translating the mockups to Pelican templates.
Anthony will continue working on frontend scaffolding and finance bits.
Eric will continue to focus on business and sales efforts, and performing code review.
Juan Luis will work with Ana in the new landing pages, and with Manuel in a new process to migrate users from legacy or deprecated configurations.
Manuel will wrap up the migration to Django 3, improve the queryability of the project configuration in our database, and refactor our task queue to improve its robustness.
Santos will add support for multiple .readthedocs.yaml files per repository.

Possible issues

The Python packaging ecosystem is evolving rapidly to accomodate for modern standards that will make our life easier, and in particular setuptools has been introducing some breaking changes in recent times. We anticipated this sort of breakage for our users so we pinned the setuptools version in late November. However, a small number of projects did not have this version cap active because of a bug on our side and experienced failing builds after a new setuptools release. We quickly fixed the problem and offered a range of possible solutions to affected projects.

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

Read the Docs newsletter - December 2021

2021-12-14T00:00:00Z

Company highlights

We successfully deployed mitigation measures against spam, and we are happy to report that the amount of abusive projects has dramatically decreased.
We started tracking usage of different parts of our application in a more systematic fashion which will enable us to make better product design decisions going forward.

New features

We revamped our support for webhooks: now they have a dedicated section in the project settings, you can customize the payload, and you can inspect the status of each webhook delivery. Interested in receiving build notifications on Slack or Discord? Now you can!

Revamped webhooks

On Read the Docs for Business, we improved our security audit logs to show information from all the organization according to its plan.

Organization audit logs

We expanded our documentation to describe how document projects with Jupyter Book and how to use Poetry for dependency management.

Thanks to our external contributor Rok Roškar.

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

Upcoming features

With the Christmas holidays coming up, we will have a few slow weeks ahead.

Ana will keep working on the complete redesign of our community site, which is already making good progress.
Anthony will work with Ana on the structure of our new community site and document our upcoming new user interface.
Eric will continue working on our commercial SSL provisioning and CDN with Santos.
Juan Luis will continue promoting our Embed API as well as wrap up his work on the Sphinx tutorial.
Manuel will adjust the new logging and spam fighting systems, and continue making progress on the new metrics infrastructure.
Santos will do the final bits of CDN work on our commercial site, finish moving our development documentation to a separate project, and continue unifying our commercial and community codebases.

Possible issues

Last week we accidentally banned a small number of legitimate users and they saw their projects temporarily blocked. As soon as we noticed this we apologized to the affected users and rolled back the ban, and the documentation is now serving normally.

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

Read the Docs newsletter - November 2021

2021-11-04T00:00:00Z

Company highlights

During the first week of November we attended the 2021 Essential Open Source Software for Science Annual Meeting, an event organized by the CZI Science team. We are thrilled to connect with projects in the Open Science ecosystem.
We upgraded our systems to Python 3.8 and Ubuntu 20.04 LTS. This will allow us to leverage newer Python features and use more up to date dependencies.
The Read the Docs tutorial we started writing as part of the CZI grant we received is now complete! We plan to keep updating it with user feedback and keep improving other parts of our documentation.

New features

We added a checkbox to subscribe to our newsletter on new signups. If you haven’t already, you can also subscribe using the form on the top right of our blog.
We no longer show the rebuild option on closed or merged pull request builds.
We now re-sync VCS accounts for SSO organization daily.

Thanks to our external contributors Adam Dangoor, Arthur Milchior, Carlton Gibson, Deepto, Jürgen Gmach, and Maksudul Haque.

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

Upcoming features

Ana will be working on bringing the mockups of our new landing pages to reality.
Anthony will keep working on finances and taxes, and helping Ana with the frontend work.
Eric will send out a report for our grant work, and work with Santos on implementing CloudFlare for our corporate site.
Juan Luis will work on moving our development documentation to a separate project, finish the Sphinx tutorial, spread the word about MyST Markdown, and promote our Embed API.
Manuel will add mechanisms to fight spam in our platform and improve our internal metrics.
Santos will wrap up the custom outgoing webhooks and keep unifying the code of our community and commercial sites.

Possible issues

The docutils 0.18 release from late October is incompatible with older versions of Sphinx, which are still used by a significant number of projects on Read the Docs. A large number of them were not pinning their dependencies and have experienced broken builds, which has resulted in a large number of issues and support requests. We have written a blog post explaining the situation and the ways to solve it.

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

Read the Docs newsletter - October 2021

2021-10-07T00:00:00Z

Company highlights

We have resumed sending our blog updates by email. You can subscribe to our newsletter so you don’t miss them.
Version 3 of our Embed API is now implemented, thanks to the CZI grant we received. We will give more details about it soon.
We have reworked our team page to give you a better idea of who we are and how we work at the company.

New features

You can now use our newer build specification that leverages a newer image based on Ubuntu 20.04 and gives more control over the versions of Python, Node.js, Rust, and Go. Projects like pypa/cryptography and thebe are already using it, and we will make an announcement with more information soon.
We have added a new section to our Dashboard that exposes user security logs.

Security logs

We have added a button on the Analytics section to download all your data, so you are not limited by the last 30 days that we show.
We have revamped our onboarding process. If you are new to Read the Docs, you can now fork our template repository and follow our tutorial to learn how to use the platform. We plan to keep expanding the tutorial during the coming weeks.
We have made our how-to guides more visible and simplified its categorization, in addition to other documentation improvements.

Thanks to our external contributors Mozi and Dmitry.

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

Upcoming features

Ana will work on the UI of our landing and marketing pages, while making progress with version 1.1 of our Sphinx theme.
Anthony will resume work on our new product interface and wrap up some financial updates.
Eric will focus on expanding our CDN functionality on the commercial site, as well as addressing some upcoming changes to how custom domains work on Read the Docs Community.
Juan Luis will document several recent changes, such us the new build specification and our support for generic webhooks, and continue expanding our tutorial and improving the SEO of our docs.
Manuel will finish the migration of our services to Ubuntu 20.04, release a new version of sphinx-hoverxref that uses our new embed API, and gather feedback on our new build specification.
Santos will continue consolidating our Community and Commercial codebases, finish the work on generic webbooks for easier integration with Slack and other tools, enable Commercial users to create new subscriptions after they cancel, and collaborate with Eric on the CDN issues.

Possible issues

We are detecting an increasing number of spammy projects on our platform. While this rarely affects legitimate users, it is still a concern to us and we are planning to take measures to tackle it.

In addition, some projects experienced networking issues due to the expiration of Let’s Encrypt root certificate. We deployed a fix shortly after the problem was reported.

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

Read the Docs newsletter - September 2021

2021-09-02T00:00:00Z

Company highlights

We have published the first release candidate of version 1.0.0 of our Sphinx theme, which adds support for recent versions of Sphinx and docutils among other things, and announced our future plans for it. Check out the linked blog post to know more. Update: We have released 1.0 to PyPI
The first part of the new Read the Docs tutorial, which we wrote as part of our CZI grant, is online! We hope that it serves as a better starting point for people seeking to learn how to use our platform.

New features

Commercial users can now share specific versions of their projects and log out from the flyout menu.
We added the possibility for users to remove themselves from a project without having to ask an owner to remove them (as long as they are not the only owner of the project).
We fixed a small usability issue with our search-as-you-type box, that ignored the first typed characters under certain circumstances.
We have documented our unofficial support for Gitea, and made other minor documentation fixes.

Thanks to our external contributors Mozi, Maksudul Haque, Stefano Costa, and Christian Clauss.

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

Upcoming features

Ana will continue researching tools for conducting automated testing on our Sphinx theme, review pull requests corresponding to the 1.1 milestone, and make some small styling improvements to our documentation.
Anthony will work with Ana on testing our Sphinx theme, in addition to resuming work on our new user interface and doing some financial updates.
Eric will keep pushing updates on our Commercial landing page and continue working on our sales processes. He’s also working to continue building EthicalAds as well.
Juan Luis will continue working on our Read the Docs tutorial, improving our onboarding experience, and put our email marketing and on-site notifications to work.
Manuel will finish the work on our new Docker images and build process, and keep designing our upcoming GitHub Application.
Santos will implement a new Slack integration, work with Manuel on the GitHub Application, and build a user interface for audit tracking.

Possible issues

We have been making changes to how we store cookies to make our site more secure. This has caused some minor issues in certain web browsers or to users that were embedding private documentation pages inside an iframe.

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

Read the Docs newsletter - August 2021

2021-08-09T00:00:00Z

Company highlights

We have a new team member! Ana just joined us as Frontend Developer in the context of the CZI grant we were awarded to work on our JavaScript documentation embedding client and the Read the Docs redesign and UX.
The first version of the tutorial we contributed to the official Sphinx documentation is online, as part of the new Sphinx 4.1 releases, and we are already working on expanding it. We thank the Sphinx maintainers for the thorough reviews and CZI for making it possible.
We are now tracking changes in our database, which will help us with support issues and additional auditing features on Read the Docs for Business.

New features

We added support for Python 3.10b4 in our testing Docker images! The final 3.10.0 release will be in October, but you can already test a development version.
Our commercial site now allows pull request previews to be public rather than private only, and to control the privacy level of pull request builds as well. As a result, we have dropped privacy levels for projects on our community site, since they used to be a source of confusion.
We released sphinx-hoverxref 0.7b1, which adds compatibility with Sphinx 4.1.
We fixed a long-standing usability issue in both our community and commercial sites: notifications now have a close button.

Button to close notifications

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

Upcoming features

Ana, our new hire, will spend some time getting familiarized with our development practices and tools, and perform some quality assurance on the upcoming new version of our Sphinx theme along with Anthony.
Anthony will work on onboarding Ana, release a first release candidate of version 1.0 of our Sphinx theme, and some finance work.
Eric will continue overseeing the implementation of the next stages of our audit tracking along with Santos, doing code review, and improving our sales & marketing processes.
Juan Luis will expand the Sphinx tutorial while doing basic bug triaging for the project, and start with a much needed tutorial for Read the Docs itself.
Manuel will keep working on our Embed API version 3, push the final tweaks needed to support Python 3.10 along with Santos, and continue improving our deployment processes.
Santos will continue with the implementation of our audit tracking, inform our users about the upcoming changes in privacy levels on our community site, and wrap up the work around sharing specific versions of commercial projects.

Possible issues

Projects that were using Git LFS on our site noticed that it stopped working at the end of June. Even though it is not officially supported from our side, we wanted to make it work again, but it took several days to understand what was happening.

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

Read the Docs newsletter - July 2021

2021-07-08T00:00:00Z

Welcome to a new edition of our monthly newsletter, where we share the most relevant updates around Read the Docs, offer a summary of new features we shipped during the previous month, and share what we’ll be focusing on in the near future.

Company highlights

Eric presented the history of the company at the Upstream 2021 conference along with ideas for open source sustainability. You can read more about it in our recent blog post.
We revamped our sustainability page to clarify the ways in which you or your project can go ad-free.
The first two parts of the Sphinx tutorial we are writing in the context of the CZI grant were merged to the development branch, and will be publicly available soon in the official Sphinx documentation.
We finalized the design of our upcoming Embed API v3, which will open up more possibilities of embedding content inside and outside Read the Docs. Watch this space for updates on the topic.
One extra person will join our team as Frontend Developer. More details coming soon!

New features

We added a new functionality to rebuild a specific PR build. A small user experience improvement that we hope is useful to many of our users (see image below).
We added a JSON schema of our configuration file to JSON Schema Store. If your editor has support for JSON schema, it will now give you autocompletion and linting for our .readthedocs.yml.

Link to rebuild a specific build

Thanks to our external contributors @mongolsteppe, Florian Bruhin, Seth Falco, Rémi Verschelde, Chris Holdgraf, and Maksudul Haque.

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

Upcoming features

Anthony will focus on getting our Sphinx theme to support Sphinx 4.0 along with our external contributor Aaron Carlisle, finishing up the financial summary of 2020, and onboarding our new Frontend hire.
Eric will continue working on our sales process and doing pull request reviews, along with managing other ongoing projects. In addition, he will push forward the proposal to add audit tracking along with Manuel.
Juan Luis is now collaborating more closely with the Sphinx team and will submit the third part of our beginners tutorial. In addition, he will lead a documentation sprint at SciPy, and start working on an introductory tutorial for Read the Docs.
Manuel has already started with the implementation of our Embed API v3 and will continue working on it for the coming weeks, apart from improving our data backups and implementing the first pieces of our audit tracking.
Santos will keep on working with the refactoring of our codebases so our commercial and community sites are easier to maintain. He will also write a new guide about how to use unsupported VCS platforms on Read the Docs.

Possible issues

Our release from June 15th contains a security advisory to our CSRF settings.

On an unrelated note, we are receiving more support requests from our users about some software versions in our Docker images, and we have decided to give that work more priority.

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

Read the Docs newsletter - June 2021

2021-06-03T00:00:00Z

Welcome to a new edition of our monthly newsletter, where we openly share the most relevant updates around Read the Docs, offer a summary of new features we shipped during the previous month, and share what we’ll be focusing on in the near future.

Company highlights

We applied to the next round of the CZI Essential Open Source Software for Science! Our proposal is even more ambitious than the previous one, and we are excited about the possibilities for our users if we get accepted. The funding would cover 2 years of work, starting in 2022.
We keep making progress on the current CZI grant work: Juan Luis sent the first pull request for our new Sphinx tutorial, which received positive feedback from the maintainers, and Manuel is about to release a new version of sphinx-hoverxref with support for intersphinx (we will write a dedicated blog post about this soon).
We added a Data Processing Agreement to our official documentation.
We are iterating on an improved roadmap workflow to make sure our team stays productive as we grow.

New features

We added a new configuration key, build.apt_packages, that allow our users to install custom operating system packages. You can read more in our dedicated blog post.
Now redirects also work if you are using HTTP.

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

Upcoming features

Anthony_ will keep working on our new UI templates as well as pushing sphinx_rtd_theme, and continue assisting with the Frontend hiring process.
Eric will continue to focus on improving the product for our Enterprise users. This includes working on auditing functionality, security process improvements, and other small features. He will also keep working on improving the ads platform.
Juan Luis will continue writing the new Sphinx tutorial and scheduling Customer Development calls with scientific users, along with advertising more options for projects to remove ads.
Manuel will wrap up the new sphinx-hoverxref release, continue working on SSO to make it discoverable by users, and keep pushing the Embed API v3 design document as well as new ideas for how our builders work.
Santos will work on enabling pull request builds of commercial projects to be public, continue unifying our community and commercial codebases, and work with Manuel on defining our new philosophy for our builders, so we can move away from injecting logic on behalf of the users and improve the extensibility of our platform (see our ongoing discussion).

Possible issues

After the recent news of GitHub and GitLab restricting their free offerings to prevent crypto mining abuse, we started researching ways to detect and prevent this situation from happening to us in the future.

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