Google Summer of Code¶
Thanks for your interest in Read the Docs! Please follow the instructions in Getting Started, as a good place to start. Contacting us will not increase your chance of being accepted, but opening Pull Requests with docs and tests will.
Read the Docs is excited to be in the Google Summer of Code in 2019. This page will contain all the information for students and anyone else interested in helping.
Incoming students will need the following skills:
- Intermediate Python & Django programming
- Familiarity with Markdown, reStructuredText, or some other plain text markup language
- Familiarity with git, or some other source control
- Ability to set up your own development environment for Read the Docs
- Basic understanding of web technologies (HTML/CSS/JS)
- An interest in documentation and improving open source documentation tools!
We’re happy to help you get up to speed, but the more you are able to demonstrate ability in advance, the more likely we are to choose your application!
The Installation doc is probably the best place to get going. It will walk you through getting a basic environment for Read the Docs setup.
Then you can look through our Contributing to Read the Docs doc for information on how to get started contributing to RTD.
People who have a history of submitting pull requests will be prioritized in our Summer of Code selection process.
Want to get involved?¶
If you’re interested in participating in GSoC as a student, you can apply during the normal process provided by Google. We are currently overwhelmed with interest, so we are not able to respond individually to each person who is interested.
Currently we have a few folks signed up:
- Eric Holscher
- Manuel Kaufmann
- Anthony Johnson
- Safwan Rahman
Please do not reach out directly to anyone about the Summer of Code. It will not increase your chances of being accepted!
We have written our some loose ideas for projects to work on here. We are also open to any other ideas that students might have.
These projects are sorted by priority. We will consider the priority on our roadmap as a factor, along with the skill of the student, in our selection process.
Collections of Projects¶
This project involves building a user interface for groups of projects in Read the Docs (
Users would be allowed to create, publish, and search a
Collection of projects that they care about.
We would also allow for automatic creation of
Collections based on a project’s
Once a user has a
we would allow them to do a few sets of actions on them:
- Search across all the projects in the
Collectionwith one search dialog
- Download all the project’s documentation (PDF, HTMLZip, Epub) for offline viewing
- Build a landing page for the collection that lists out all the projects, and could even have a user-editable description, similar to our project listing page.
There is likely other ideas that could be done with
Collections over time.
Integration with OpenAPI/Swagger¶
This could include:
- Building a live preview for testing an API in the documentation
- Taking a swagger YAML file and generating HTML properly with Sphinx
- Integration with our existing API to generate Swagger output
Autobuild docs for Pull Requests¶
It would be great to automatically build docs for Pull Requests in GitHub repos that our users have. Currently we don’t support this, and it’s one of our most requested features.
This would include:
- Modeling Pull Requests as a type of version alongside Tags and Branches
- Modifying how we upload HTML docs to store them in a place like S3 for long term storage
- Build integration with GitHub to send the status notifications when a PR is building and complete
More info here:
Build a new Sphinx theme¶
Sphinx v2 will introduce a new format for themes, supporting HTML5 and new markup. We are hoping to buid a new Sphinx theme that supports this new structure.
This project would include:
- A large amount of design, including working with CSS & SASS
- Iterating with the community to build something that works well for a number of use cases
This is not as well defined as the other tasks, so would require a higher level of skill from an incoming student.
Better MkDocs integration¶
Currently we don’t have a good integration with MkDocs as we do with Sphinx. And it’s hard to maintain compatibility with new versions.
This project would include:
Right now it’s hard for users to rename files. We support redirects, but don’t create them automatically on file rename, and our redirect code is brittle.
We should rebuild how we handle redirects across a number of cases:
- Detecting a file change in git/hg/svn and automatically creating a redirect
- Support redirecting an entire domain to another place
- Support redirecting versions
There will also be a good number of things that spawn from this, including version aliases and other related concepts, if this task doesn’t take the whole summer.
Improve Translation Workflow¶
Currently we have our documentation & website translated on Transifex, but we don’t have a management process for it. This means that translations will often sit for months before making it back into the site and being available to users.
This project would include putting together a workflow for translations:
- Communicate with existing translators and see what needs they have
- Help formalize the process that we have around Transifex to make it easier to contribute to
- Improve our tooling so that integrating new translations is easier
Support for additional build steps for linting and testing¶
Currently we only build documentation on Read the Docs, but we’d also like to add additional build steps that lets users perform more actions. This would likely take the form of wrapping some of the existing Sphinx builders, and giving folks a nice way to use them inside Read the Docs.
It would be great to have wrappers for the following as a start:
- Link Check (http://www.sphinx-doc.org/en/stable/builders.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder)
- Spell Check (https://pypi.python.org/pypi/sphinxcontrib-spelling/)
- Doctest (http://www.sphinx-doc.org/en/stable/ext/doctest.html#module-sphinx.ext.doctest)
- Coverage (http://www.sphinx-doc.org/en/stable/ext/coverage.html#module-sphinx.ext.coverage)
The goal would also be to make it quite easy for users to contribute third party build steps for Read the Docs, so that other useful parts of the Sphinx ecosystem could be tightly integrated with Read the Docs.