222 lines
12 KiB
HTML
222 lines
12 KiB
HTML
<!--lint ignore awesome-git-repo-age-->
|
||
<!--lint disable double-link-->
|
||
<!-- title -->
|
||
<h1 id="awesome-read-the-docs-awesome-lint">Awesome Read the Docs <a
|
||
href="https://awesome.re"><img src="https://awesome.re/badge.svg"
|
||
alt="Awesome" /></a> <a
|
||
href="https://github.com/readthedocs-examples/awesome-read-the-docs/actions/workflows/lint.yaml"><img
|
||
src="https://github.com/readthedocs-examples/awesome-read-the-docs/actions/workflows/lint.yaml/badge.svg"
|
||
alt="lint" /></a></h1>
|
||
<!-- subtitle -->
|
||
<blockquote>
|
||
<p>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.</p>
|
||
</blockquote>
|
||
<!-- image -->
|
||
<p><a href="https://docs.readthedocs.io/en/stable/tutorial/index.html" target="_blank" rel="noopener noreferrer">
|
||
<img src="./readthedocs-logo.svg" /> </a></p>
|
||
<!-- description -->
|
||
<p>Read the Docs is a fully open-source platform that builds and
|
||
publishes documentation. Read more on https://about.readthedocs.com.</p>
|
||
<h2 id="foreword">Foreword</h2>
|
||
<p>Many new and exciting documentation projects have emerged in
|
||
<em>science and academia</em>, 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.</p>
|
||
<p>In addition to showing awesome and real-life Read the Docs projects,
|
||
a number of <a href="#example-projects">Example Projects</a> are being
|
||
built to help people learn and get started.</p>
|
||
<p>We hope that this will inspire people writing documentation,
|
||
developing new documentation projects or updating existing ones. All
|
||
projects mentioned here are <strong>open source</strong>, meaning that
|
||
you can find their source code and understand how it’s done.</p>
|
||
<p>The list is a work in progress, please feel invited to <a
|
||
href="#contributing">contribute</a>!</p>
|
||
<!-- TOC -->
|
||
<!--lint disable awesome-toc-->
|
||
<h2 id="contents">Contents</h2>
|
||
<!--lint enable awesome-toc-->
|
||
<ul>
|
||
<li><a href="#sphinx-projects">Sphinx projects</a></li>
|
||
<li><a href="#mkdocs-projects">MkDocs projects</a></li>
|
||
<li><a href="#api-reference">API Reference</a></li>
|
||
<li><a href="#science-projects">Science projects</a></li>
|
||
<li><a href="#tag-cloud">Tag cloud</a></li>
|
||
</ul>
|
||
<!-- CONTENT -->
|
||
<h2 id="sphinx-projects">Sphinx projects</h2>
|
||
<ul>
|
||
<li><a href="https://crate.io/docs/crate/">CrateDB</a> - 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, <a
|
||
href="https://github.com/crate/crate-docs-theme">crate-docs-theme</a> to
|
||
orchestrate the projects and align them. <strong>#sphinx</strong>
|
||
<strong>#custom-theme</strong>.</li>
|
||
<li><a href="https://docs.django-cms.org/">django-cms</a> - django-cms’s
|
||
developer documentation is as extensive as it’s well-organized. It uses
|
||
the Furo theme. <strong>#sphinx</strong>
|
||
<strong>#large-project</strong>.</li>
|
||
<li><a href="https://docs.ray.io/">Ray</a> - Ray is a documentation
|
||
project spanning multiple software components. It uses several
|
||
extensions from the Executable Book project. Features are showcased in
|
||
<a
|
||
href="https://twitter.com/readthedocs/status/1663923671470047234">this
|
||
twitter thread</a>. <strong>#sphinx</strong> <strong>#themes</strong>
|
||
<strong>#large-project</strong>.</li>
|
||
<li><a href="https://docs.scrapy.org/">Scrapy</a> - Embeds a lot of
|
||
reference snippets and uses <code>sphinx-hoverxref</code> for quick
|
||
reference tooltips. Lots of inspiration to be found in content
|
||
organization. <strong>#sphinx</strong>.</li>
|
||
<li><a href="https://setuptools.pypa.io/">setuptools</a> - Lots of
|
||
features, using the Furo theme. <a
|
||
href="https://twitter.com/readthedocs/status/1546527820150718469">Twitter
|
||
thread</a> with some examples. <strong>#sphinx</strong>
|
||
<strong>#themes</strong>.</li>
|
||
<li><a href="https://sphinx-needs.readthedocs.io/">sphinx-needs</a> -
|
||
Documentation of <code>sphinx-needs</code>. <strong>#sphinx</strong>
|
||
<strong>#themes</strong>.</li>
|
||
<li><a
|
||
href="https://sphinx-immaterial.readthedocs.io/">sphinx-immaterial</a> -
|
||
Documentation of <code>sphinx-immaterial</code>, a Material theme for
|
||
Sphinx, based on Material for MkDocs. <strong>#sphinx</strong>
|
||
<strong>#themes</strong>.</li>
|
||
<li><a href="https://manual.uberspace.de/">Uberspace</a> - Customized
|
||
sidebar and footer, adding project’s branding through custom CSS and
|
||
HTML to <code>sphinx_rtd_theme</code>. Latest version and release date
|
||
on front page. <strong>#sphinx</strong> <strong>#themes</strong>
|
||
<strong>#custom-theme</strong>.</li>
|
||
<li><a href="https://docs.wagtail.org/">Wagtail</a> - 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 <a
|
||
href="https://docs.wagtail.org/en/stable/releases/index.html">Release
|
||
Notes</a> and <a
|
||
href="https://docs.wagtail.org/en/stable/contributing/index.html">Contribution
|
||
guide</a> are remarkable. Wagtail’s documentation uses a minimal set of
|
||
Sphinx extensions. <strong>#sphinx</strong> <strong>#themes</strong>
|
||
<strong>#diataxis</strong>.</li>
|
||
<li><a href="https://docs.weblate.org/">Weblate</a> - 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. <strong>#sphinx</strong> <strong>#themes</strong>
|
||
<strong>#translation</strong>.</li>
|
||
</ul>
|
||
<h2 id="mkdocs-projects">MkDocs projects</h2>
|
||
<ul>
|
||
<li><a href="https://argo-cd.readthedocs.io/">Argo CD</a> - 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. <strong>#mkdocs</strong>
|
||
<strong>#themes</strong> <strong>#large-project</strong>.</li>
|
||
<li><a href="https://doc2dash.readthedocs.io/">doc2dash</a> - Material
|
||
for MkDocs with a custom version provider fully compatible with Read the
|
||
Docs <strong>#mkdocs</strong> <strong>#themes</strong>.</li>
|
||
<li><a href="https://docs.nautobot.com/">Nautobot</a> - Extensive usage
|
||
of the subprojects feature to organize numerous documentation projects
|
||
under the same custom domain / landing page. Each subproject has its own
|
||
release cycle. Features are showcased in <a
|
||
href="https://twitter.com/readthedocs/status/1595010133796462593">this
|
||
twitter thread</a>. <strong>#mkdocs</strong> <strong>#themes</strong>
|
||
<strong>#large-project</strong>.</li>
|
||
<li><a href="https://docs.sidra.dev/en/latest/">Sidra Data Platform</a>
|
||
- Material for MkDocs theme with version selector and search integrated
|
||
via Read the Docs Addons. <strong>#mkdocs</strong>
|
||
<strong>#themes</strong> <strong>#business</strong>.</li>
|
||
<li><a href="https://docs.haskellstack.org/">The Haskell Tool Stack</a>
|
||
- A matured MkDocs project using their documentation website as their
|
||
main website. Notice both the structure and the considerate use of
|
||
widgets included in Material for MkDocs <strong>#mkdocs</strong>
|
||
<strong>#themes</strong>.</li>
|
||
</ul>
|
||
<h2 id="api-reference">API Reference</h2>
|
||
<ul>
|
||
<li><a href="https://discordpy.readthedocs.io/">discord.py</a> - This
|
||
projects very rich Python API reference uses custom extension for quick
|
||
overview tables of attributes and methods +
|
||
<code>sphinx-hoverxref</code> for tooltips with API reference + source
|
||
link references for GitHub source code. <strong>#apidocs</strong>
|
||
<strong>#sphinx</strong> <strong>#themes</strong></li>
|
||
</ul>
|
||
<h2 id="science-projects">Science projects</h2>
|
||
<ul>
|
||
<li><a href="https://aiida-qe-demo.readthedocs.io/">AiiDA
|
||
demonstration</a> - A hardware demo/tutorial written with lots of
|
||
examples and illustrations. <a
|
||
href="https://github.com/chrisjsewell/aiida-qe-demo">Behind the
|
||
scenes</a>, Conda is used by installing mambaforge and storing the setup
|
||
in <code>environment.yml</code>. <strong>#sphinx</strong>
|
||
<strong>#jupyter-notebook</strong></li>
|
||
<li><a href="https://crest.readthedocs.io/">Crest Ocean System</a> -
|
||
Uses sphinx-hoverxref and Executable Book. Video tutorials in text. Lots
|
||
of embeds, Trello, YouTube and more. <strong>#sphinx</strong>
|
||
<strong>#themes</strong></li>
|
||
<li><a href="https://jupyterbook.org/">jupyter-book</a> - Jupyter-book
|
||
automatically creates Sphinx projects from projects that are friendly to
|
||
Jupyter Notebook users. <strong>#jupyter-notebook</strong>
|
||
<strong>#sphinx</strong> <strong>#diataxis</strong>.</li>
|
||
<li><a href="https://jupyter-sphinx.readthedocs.io/">jupyter-sphinx</a>
|
||
- Directly executes and renders Jupyter Notebooks in documentation
|
||
projects. <strong>#jupyter-notebook</strong>
|
||
<strong>#sphinx</strong>.</li>
|
||
<li><a
|
||
href="https://jupyter-tutorial.readthedocs.io/">jupyter-tutorial</a> -
|
||
Uses a set of extensions for Sphinx, for instance direct rendering of
|
||
<code>.ipynb</code> files with <code>nbsphinx</code>.
|
||
<strong>#jupyter-notebook</strong> <strong>#sphinx</strong>.</li>
|
||
<li><a href="https://msticpy.readthedocs.io/">msticpy</a> - MSTIC
|
||
Jupyter and Python Security Tools, msticpy is a library for InfoSec
|
||
investigation and hunting in Jupyter Notebooks.
|
||
<strong>#jupyter-notebook</strong> <strong>#sphinx</strong>.</li>
|
||
<li><a href="https://nbsphinx.readthedocs.io/">nbsphinx</a> - Banner and
|
||
buttons to view interactive versions of currently displayed
|
||
<code>*.ipynb</code> files using the Binder service. Notice also the
|
||
awesome PDF version. <strong>#jupyter-notebook</strong>
|
||
<strong>#sphinx</strong>.</li>
|
||
<li><a href="https://docs.poliastro.space/">poliastro</a> - An extensive
|
||
science project, demonstrating rich use of math formulas, interactive
|
||
plotting in 3d, <code>sphinx-hoverxref</code>, custom 404s and a nice
|
||
copy button on code examples. Notice how well the navigation reflects
|
||
the <a href="https://diataxis.fr/">Diátaxis framework</a>
|
||
<strong>#sphinx</strong> <strong>#diataxis</strong>.</li>
|
||
<li><a href="https://docs.sunpy.org/">SunPy</a> - A large documentation
|
||
project for an open-source package for solar physics. Embeds the main
|
||
website’s menu and uses a custom theme. Extensive changelog and release
|
||
notes. <strong>#custom-theme</strong>, <strong>sphinx</strong>,
|
||
<strong>#apidocs</strong>.</li>
|
||
<li><a href="https://torchio.readthedocs.io/">TorchIO</a> - An
|
||
open-source Python library targeting 3D medical images in deep learning.
|
||
Combines API documentation with usage examples, uses “single version”
|
||
for a singular “rolling release” documentation. <a
|
||
href="https://twitter.com/readthedocs/status/1570339818806120450">Screenshots
|
||
in this Twitter thread</a>. <strong>#themes</strong>,
|
||
<strong>sphinx</strong>.</li>
|
||
<li><a href="https://tomobank.readthedocs.io/">TomoBank</a> - A big list
|
||
of tomographic datasets and phantoms, featuring especially tables and
|
||
images and maintained by science community.
|
||
<strong>#sphinx</strong>.</li>
|
||
</ul>
|
||
<!-- END CONTENT -->
|
||
<h2 id="tag-cloud">Tag cloud</h2>
|
||
<p>The categories in this list are intersecting at the following
|
||
tags:</p>
|
||
<p><strong>#sphinx</strong>, <strong>#mkdocs</strong>,
|
||
<strong>#themes</strong>, <strong>#custom-theme</strong>,
|
||
<strong>#jupyter-notebook</strong>, <strong>#diataxis</strong>,
|
||
<strong>#large-project</strong>, <strong>#apidocs</strong>,
|
||
<strong>#translation</strong></p>
|
||
<h2 id="contributing">Contributing</h2>
|
||
<p><a href="contributing.md">Contributions of any kind welcome, just
|
||
follow the guidelines</a>!</p>
|
||
<h3 id="contributors">Contributors</h3>
|
||
<p><a
|
||
href="https://github.com/readthedocs-examples/awesome-read-the-docs/graphs/contributors">Thanks
|
||
goes to these contributors</a>!</p>
|
||
<p><a
|
||
href="https://github.com/readthedocs-examples/awesome-read-the-docs">readthedocs.md
|
||
Github</a></p>
|