Awesome read the docs

Awesome Read the Docs ¶

> 很棒的文档项目的精选列表，对于学习和引导新的文档项目很有用. > 加上“阅读文档”在现实生活中的酷炫用法.

Read the Docs 是一个完全开源的平台，用于构建和发布文档. 阅读更多内容 readthedocs.org 和 readthedocs.com （阅读商业文档）.

Foreword¶

“科学和学术界”出现了许多令人兴奋的新文档项目，使文档世界超越了软件项目. 为了捕捉最新的发展和趋势，我们正在编制一份文档技术的鼓舞人心的用途列表，特别是在传统的软件文档领域之外.

除了展示精彩且真实的“阅读文档”项目外，还有许多 Example Projects 旨在帮助人们学习和入门.

我们希望这能够激励人们编写文档、开发新的文档项目或更新现有的文档项目. 这里提到的所有项目都是开源，这意味着您可以找到它们的源代码并了解它是如何完成的.

该列表正在制作中，请受邀参与 contribute!

Sphinx projects¶

CrateDB - Crate.io 已将他们的文档经验集成到他们的通用网站中. 总共嵌套了 15 个文档项目. 他们使用自定义主题， 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 是一个涵盖多个软件组件的文档项目. 它使用 Executable Book 项目的多个扩展. 功能展示于 this twitter thread. #sphinx #themes #large-project.
Scrapy - Embeds a lot of reference snippets and uses sphinx-hoverxref for quick reference tooltips. Lots of inspiration to be found in content organization. #sphinx.
setuptools - 很多功能，使用 Furo 主题. 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 和 developers), has it's own beautiful theme 和 is largely structured around Diátaxis ideals. The Release Notes 和 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.
Nautobot - 广泛使用子项目功能在同一自定义域/登陆页面下组织大量文档项目. 每个子项目都有自己的发布周期. 功能展示于 this twitter thread. #mkdocs #themes #large-project.
The Haskell Tool Stack - 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 #mkdocs #themes.

API Reference¶

discord.py - This projects very rich Python API reference uses custom extension for quick overview tables of attributes and methods + sphinx-hoverxref for tooltips with API reference + source link references for GitHub source code. #apidocs #sphinx #themes

Science projects¶

AiiDA demonstration - 包含大量示例和插图的硬件演示/教程. Behind the scenes, Conda is used by installing mambaforge and storing the setup in environment.yml. #sphinx #jupyter-notebook
Crest Ocean System - Uses sphinx-hoverxref and Executable Book. Video tutorials in text. Lots of embeds, Trello, YouTube and more. #sphinx #themes
jupyter-book - Jupyter-book automatically creates Sphinx projects from projects that are friendly to Jupyter Notebook users. #jupyter-notebook #sphinx #diataxis.
jupyter-sphinx - Directly executes and renders Jupyter Notebooks in documentation projects. #jupyter-notebook #sphinx.
jupyter-tutorial - Uses a set of extensions for Sphinx, for instance direct rendering of .ipynb files with nbsphinx. #jupyter-notebook #sphinx.
msticpy - MSTIC Jupyter and Python Security Tools, msticpy is a library for InfoSec investigation and hunting in Jupyter Notebooks. #jupyter-notebook #sphinx.
nbsphinx - Banner and buttons to view interactive versions of currently displayed *.ipynb files using the Binder service. Notice also the awesome PDF version. #jupyter-notebook #sphinx.
poliastro - 一个广泛的科学项目，展示了数学公式的丰富使用、3D 交互式绘图、“sphinx-hoverxref”、自定义 404 以及代码示例上漂亮的复制按钮. 请注意导航如何很好地反映 Diátaxis framework #sphinx #diataxis.
SunPy - 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. #custom-theme, sphinx, #apidocs.
TorchIO - 一个针对深度学习中 3D 医学图像的开源 Python 库. 将 API 文档与使用示例相结合，使用“单一版本”表示单个“滚动发布”文档. Screenshots in this Twitter thread. #themes, sphinx.
TomoBank - A big list of tomographic datasets and phantoms, featuring especially tables and images and maintained by science community. #sphinx.

Example projects¶

Basic Sphinx example - Basic example of using Sphinx on Read the Docs. #sphinx.
Basic MkDocs example - Basic example of using MkDocs on Read the Docs. #mkdocs.
Jupyter Book example - Using Jupyter Book on Read the Docs with popular extensions. #jupyter-notebook #sphinx.

此列表中的类别在以下标签处交叉：

#sphinx, #mkdocs, #themes, #custom-theme, #jupyter-notebook, #diataxis, #large-project, #apidocs, #translation

Contributing¶

Contributions of any kind welcome, just follow the guidelines!

Contributors¶

Thanks goes to these contributors!

Awesome read the docs

Awesome read the docs