rhetenor/awesome-awesomeness
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Jonas Zeunert
2025-07-18 23:13:11 +02:00
parent c9485bf576
commit 652812eed0
2354 changed files with 1266414 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
html/readthedocs.md2.html Normal file
View File

@@ -0,0 +1,221 @@
<!--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>