Awesome Read the Docs
A curated list of awesome documentation projects, useful to learn from and for bootstrapping new documentation projects. Plus cool real-life usages of Read the Docs.
Read the Docs is a fully open-source platform that builds and publishes documentation. Read more on https://about.readthedocs.com.
Foreword
Many new and exciting documentation projects have emerged in science and academia, taking the world of documentation beyond just software projects. To capture the latest development and trends, we are compiling a list of inspirational uses of documentation technology, especially outside of the traditional field of software documentation.
In addition to showing awesome and real-life Read the Docs projects, a number of Example Projects are being built to help people learn and get started.
We hope that this will inspire people writing documentation, developing new documentation projects or updating existing ones. All projects mentioned here are open source, meaning that you can find their source code and understand how it's done.
The list is a work in progress, please feel invited to contribute!
Contents
Sphinx projects
- CrateDB - Crate.io has integrated their documentation experience into their general website. There's a total of 15 documentation projects nested. They use a custom theme, crate-docs-theme to orchestrate the projects and align them. #sphinx #custom-theme.
- django-cms - django-cms's developer documentation is as extensive as it's well-organized. It uses the Furo theme. #sphinx #large-project.
- Ray - Ray is a documentation project spanning multiple software components. It uses several extensions from the Executable Book project. Features are showcased in this twitter thread. #sphinx #themes #large-project.
- Scrapy - Embeds a lot of reference snippets and uses
sphinx-hoverxreffor quick reference tooltips. Lots of inspiration to be found in content organization. #sphinx. - setuptools - Lots of features, using the Furo theme. Twitter thread with some examples. #sphinx #themes.
- sphinx-needs - Documentation of
sphinx-needs. #sphinx #themes. - sphinx-immaterial - Documentation of
sphinx-immaterial, a Material theme for Sphinx, based on Material for MkDocs. #sphinx #themes. - Uberspace - Customized sidebar and footer, adding project's branding through custom CSS and HTML to
sphinx_rtd_theme. Latest version and release date on front page. #sphinx #themes #custom-theme. - Wagtail - Wagtail is a Django-based CMS with a global community. The documentation spans multiple stakeholders (editors and developers), has it's own beautiful theme and is largely structured around Diátaxis ideals. The Release Notes and Contribution guide are remarkable. Wagtail's documentation uses a minimal set of Sphinx extensions. #sphinx #themes #diataxis.
- Weblate - Weblate is a translation platform with a large documentation project with many translations and customized Read the Docs theme. Documentation aimed at all segments: users, administrators and developers. Also features an extensive Changelog. #sphinx #themes #translation.
MkDocs projects
- Argo CD - Material for MkDocs theme with custom colors and a nice version drop down. Animated product demo and carefully designed sidebar presenting targeted guides for Operators, Users and Developers. #mkdocs #themes #large-project.
- doc2dash - Material for MkDocs with a custom version provider fully compatible with Read the Docs #mkdocs #themes.