Read the Docs Blog - Posts from Bend, Oregon

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 Community downtime due to migrations to AWS

2021-02-05T00:00:00Z

Update: The migration was successful and the site has been fully restored as of 4PM PST.

We wanted to make you aware that on Friday, February 12th at 1pm PST (4pm EST, 21:00 UTC), Read the Docs Community (readthedocs.org) will be having a scheduled dashboard downtime of approximately 4 hours.

To ensure minimal impact for our users, we are performing this upgrade during a Friday afternoon which is one of our lowest usage periods.

During this maintenance window, documentation will continue to be online but new documentation builds will not trigger and the Read the Docs dashboard will be unavailable. New builds and webhooks will begin processing once the maintenance is over.

We are moving our service to our new home on Amazon Web Services who have generously provided us with credits to support open source software. This is the same platform which Read the Docs for Business is hosted, which will allow us to reuse a lot of the same code between the sites. This should simplify our operations considerably.

We’d like to thank Microsoft Azure for sponsoring our hosting for the past 2.5 years.

Thanks for your understanding of this maintenance downtime.

Pull Request Builders available for all users

2021-01-27T00:00:00Z

We’re excited to announce that Pull Request building is now available for all Read the Docs users. We have been working on this feature for over a year, and having it available for all our users is a major milestone.

This feature allows users to confirm documentation builds correctly for all of their commits, not just ones merged into branches that are activated on Read the Docs. This moves documentation into your continuous integration pipeline, and improves the workflow for everyone working on documentation.

GitHub Build Status Reporting for Pull Requests

You can read more about this new feature in our previous blog post announcing it and in our documentation for the feature.

Serving docs for every branch

Along with building and validating each branch on your repository, we also host a rendered version of the documentation. This allows you to see exactly how the docs will look when they are deployed.

Building the documentation on Read the Docs during the development process also helps test integration with Read the Docs. The entire build process is run for each commit, so this will ensure that builds work as expected when you’re ready to merge into production.

These previews will stay live for 90 days from the time you merge or close the Pull Request, allowing you to finish any outstanding work on the task.

Limitations

Due to the increased demand for build resources, the Pull Request builders have the following limitations:

Read the Docs search is not enabled on these versions
Only HTML versions of the documentation are built (not PDF, ePub, etc.)
Documentation builds are concurrency limited. Read the Docs for Business concurrency varies based on your plan, and Read the Docs Community are limited to 2 concurrent builds.

We are working to address these limitations over time, but given the increase in scale with these builds it will take some time.

Give us feedback

We always love to hear from our users about the product. If you have feedback on this feature of any others, you can always reach us at hello@readthedocs.org.

Read the Docs for Business Maintenance Window - February 5

2021-01-25T00:00:00Z

Update: This maintenance window has concluded at 5:40 PM PST.

We wanted to make you aware that on Friday, February 5 at 5:00pm PST (8:00pm EST, Saturday 01:00 UTC), Read the Docs for Business (readthedocs.com) will be having a scheduled downtime of approximately 2 hours.

To ensure minimal impact for our users, we are performing this upgrade during a Friday afternoon which is one of our lowest usage periods. This maintenance window is for a required database version upgrade which we couldn’t perform in place. While these kinds of things do happen from time to time, we haven’t had a scheduled downtime on Read the Docs for Business in a few years. Doing this helps us ensure that our services perform well and have up-to-date security.

Thanks for your understanding of this maintenance downtime.

Read the Docs team

Read the Docs is hiring for multiple positions

2021-01-06T00:00:00Z

Read the Docs received a grant to support scientific software at the beginning of this year. As part of this, we are hiring for two new positions related to the grant work:

A frontend developer with design skills
A developer advocate with documentation skills (This position has been filled, and is no longer active)

Please look at each of the job postings for much more detail on what to expect with the job.

We are excited to be able to expand our small team and increase the support we’re giving to the scientific open source community. Throughout 2021 we are going to be vastly improving our documentation and building major new features around embedding documentation content, based on the work from this grant.

How hiring will be structured

The way we are currently planning to structure this work is to have 50% of the time spent working on grant work, and the other 50% working on Read the Docs itself. The codebase and community we’re building require a good amount of onboarding time, so we are excited to be able to use the grant funds to also improve the overall experience of Read the Docs users.

You can apply to the jobs with the links above to the full job descriptions, where you will be asked to fill out a form with a few questions.

About Read the Docs

Read the Docs is a large open source project providing documentation building and hosting. You can think of it a continuous integration for docs. We do around 500 million pageviews each year. We are a small team, but this role will have a large impact of millions of users. Almost all of our codebase is open source and we feel strongly about supporting the community while sustaining the project in an ethical manner.