Posts from Portland, Oregon
Starting this week, we’ll be deploying a new default image for our documentation build environments. This image will change the default Python versions that are supported.
We aren’t expecting any issues to arise from this change, but be sure to raise
any issues on our issue tracker if you notice any strange behavior. The new
build image supports Python
2.7 and Python
3.5, dropping support for
3.4. If you require access to Python
3.4, we suggest you sign up
for access to our next beta image.
Congrats, you made it through 2016! Read the Docs has been rolling along, and we’ve had another interesting year as well.
For a quick summary:
Today we’re excited to announce our latest project: https://pydoc.io. This work was made possible by the MOSS Grant from Mozilla. Thanks to Mozilla for funding our time building this wonderful community resource.
Running Read the Docs, we’ve always been proud of the documentation tooling that the Python community has. We prioritize prose over API documentation listings, and generally have a high standard of documentation in our projects.
Sentry was a natural first partner, both because they have a long history supporting and contributing to the open source community, and because they also strive to support open source while building a sustainable business around their project.
Starting today, Read the Docs will start hosting projects from subdomains on
readthedocs.io, instead of on
readthedocs.org. This change
addresses some security concerns around site cookies while hosting user
generated data on the same domain as our dashboard.
Changes to provide security against broader threats have been in place for a while, however there are still a few scenarios that can only be addressed by migrating to a separate domain.
On Monday, we enabled an ad space on documentation pages hosted on readthedocs.org. We have tested the ad space in the past, and had followed up with a discussion of the implications of advertising. The space was meant to be totally unobtrusive to the browsing and usage of documentation pages, and doesn’t enable third-party tracking of users in any way. This is all in an effort to help raise funds to support continued support and maintenance on the project, and ensure free and open documentation stays available.
Read the Docs is a massive project, and requires a large amount of work to keep running and support. We receive support requests and must tend to the operations of the servers on a daily basis. Neither of these tasks lend to volunteer contributions, they both require dedicated support roles for such a large site. I’ve personally been wearing a pager in support of the project for over 4 years, all on a volunteer basis.
2015 has been another great year for Read the Docs. We’ve addressed some long-standing issues like not having Markdown support, and built a number of wonderful tools for the documentation community.
You can always see our stats for the last 30 days.
Several months back, Mozilla launched a new initiative – the MOSS program – to provide financial support to the open source software projects it relies on. Mozilla allocated $1 million to the MOSS fund to provide grants for up to 10 projects matching the program’s criteria.
Read the Docs is among the first round of awards made for the MOSS program. Our proposed grant, for $48,000, is to build a separate instance that integrates with the Python Package Index’s upcoming website, Warehouse. This integration will provide automatic API reference documentation upon package release, with authentication tied to PyPI and simple configuration inside the distribution. API reference documentation on every release will be the starting point of this work, prose documentation generation will be more difficult here, as not all packages use Sphinx or rST for documentation.
Read the Docs is built on top of Sphinx, which has always relied on reStructuredText as an input mechanism. We have long heard from folks that they want to write documentation in Markdown, as well as RST.
Today we are announcing that this is now possible! With the standardization of Markdown into Commonmark, we have the ability to support a markup language with a proper spec. recommonmark is the bridge that allows Commonmark to be used inside Sphinx. This allows you to use both RST and Commonmark inside of your Sphinx project.
We’ve recently introduced a new build container subsystem based on Docker to readthedocs.org, which should go mostly unnoticed for users. We’re still ironing out some bugs with the system, so raise an issue on our issue tracker if you are noticing any new issues with your project builds.
This new system is part of an over-due security update to help isolate arbitrary code execution. As Read the Docs has grown, protecting against arbitrary execution was a rapidly growing concern. This build isolation layer was developed as part of readthedocs.com, where security concerns are paramount due to private repository access. We’ve been testing it for roll out on the community site since then, but hadn’t committed to switching production build servers over due to the number of possible side effects.
August has historical significance for Read the Docs, so it seemed fitting to wrap up August by taking a moment to step back and reflect on what we’ve done in the last year.
What makes August so significant for us?
August was a hectic month for us. So busy, in fact, we never wrote this update. We dropped the ball on getting this report out on time, but hope to keep on top of future updates.
July was a month of stability fixes, with some substantial changes to our infrastructure. First, here’s an update on some of the goals we had set with our last monthly update:
August was a busy month for us. Write the Docs Europe was at the end of the month, and our focus has been on getting readthedocs.com into a public beta state. We’re nearing the end of the 3 month period that we budgeted for as part of our fundraiser and have a few more tasks to push out.
First, an update of the goals we set for this month:
With the Write the Docs conference wrapped up in May, we shifted our focus back to Read the Docs for the remainder of May and June. Following our post on contract positions available with Read the Docs, we hired two contractors to work with us and focus on support and stability for readthedocs.org. Gregor Müllegger will be working on support and development, and Andrew Kreps has helped us on building and improving our operations infrastructure.
Read the Docs had the following major updates in June:
Thanks to our successful fundraiser, we have the ability to pay people to work on Read the Docs.
We have two positions that we are looking for:
First off, a big ol’ thank you is in order for everyone that helped support us. You all helped us hit our funding goal, and with time to spare. We’re humbled to have such an abundance of support, and to know so many people share our vision for great documentation.
Really, thank you all. ❤
2014 has been another banner year for Read the Docs. The project has been steadily growing in the open source ecosystem, expanding a good deal outside of the Python community. We have built a bunch of fantastic new features, and continued improving the documentation experience for the open source world.
You can always see our latest 30 days stats at http://www.seethestats.com/site/readthedocs.org.
Today we are announcing User-defined Redirects for Read the Docs. This has been a long requested feature that should cut down on 404’s when migrating your documentation.
Read the Docs has long had Redirects, but they are managed automatically for only certain use cases. This change allows users to control a specific set of common redirects.
Documentation is an often overlooked part of a software project. Today we are releasing badges for your docs, so that people can easily see that your docs are up-to-date.
The main use of badges is to show the status of your project’s build. They will display in green for passing, red for failing, and yellow for unknown states.
Welcome to the Read the Docs blog.
We will be doing regular feature announcements on the blog as we build them. There are also a number of recently released features that we’ll highlight there as well.
2013 has been a big year for Read the Docs. Our mission is to make documentation hosting easier, with the overall goal of increasing the quality of documentation in the programming world. I believe that we have been doing good work towards that goal, and I want to share some numbers to reflect our progress.
Our community has been great this year. I have been really happy to see a few people submit multiple patches and features. This year, we had:
We have looked at how people use documentation, and built a beautiful and highly functional new interface for browsing documentation. We created a solution that looks great and works well.