撰写文档#

注意

深受 Django 项目指南的启发

我们高度重视文档的一致性、可读性和完整性。如果一个功能没有文档,那么它就不存在。如果一个行为没有文档,那么它就是一个 bug!我们努力像对待代码一样对待文档:我们旨在尽可能频繁地改进它。

文档更改通常有两种形式

  • 一般改进:通过更清晰的措辞和更多示例来更正拼写错误、修复错误并提供更好的解释。

  • 新功能:自上次发布以来已添加到框架中的功能的文档。

本节解释了作者如何以最有用且最不易出错的方式制作文档更改。

获取原始文档#

尽管 TLJH 的文档旨在以 HTML 格式在 https://the-littlest-jupyterhub.readthedocs.io/ 阅读,但我们将其作为文本文件集合进行编辑,以实现最大的灵活性。这些文件位于 TLJH 仓库的顶级 docs/ 目录中。

如果您想开始为我们的文档做贡献,请从源代码仓库获取 TLJH 的开发版本。开发版本拥有最新最好的文档,就像它拥有最新最好的代码一样。

Sphinx 入门#

TLJH 的文档使用 Sphinx 文档系统,该系统又基于 docutils。基本思想是将轻度格式化的纯文本文档转换为 HTML、PDF 和任何其他输出格式。

要在本地构建文档,请安装 Sphinx 依赖项

$ cd docs/
$ pip install -r requirements.txt

然后从 docs 目录构建 HTML

$ make html

如果您遇到此错误,很可能是您在虚拟环境中运行。

Error in "currentmodule" directive:

要开始贡献,您需要熟悉 MarkdownMyST

您本地构建的文档的主题将与 the-littlest-jupyterhub.readthedocs.io 上的文档不同。这没关系!如果您的更改在您的本地机器上看起来不错,那么它们在网站上也会看起来不错。

文档的组织方式#

文档分为几个类别

  • 教程通过一系列步骤引导读者创建一些东西。

    教程中重要的是帮助读者实现一些有用的东西,最好是尽快,以给予他们信心。

    解释我们正在解决的问题的性质,以便读者了解我们正在努力实现的目标。不要觉得你需要从解释事情的运作方式开始——重要的是读者做了什么,而不是你解释了什么。回顾你所做的事情并事后解释可能会有所帮助。

    安装教程是教程的一个特殊子类别,它教用户如何在各种云提供商/裸机系统上安装 TLJH。这些应该与文档的其他部分大量交叉链接,尽可能避免强制用户学习 SSH 并包含大量屏幕截图。

  • 主题指南旨在从较高层面解释一个概念或主题。

    链接到参考资料而不是重复它。使用示例,不要不愿意解释对您来说似乎非常基本的东西——这可能是其他人需要的解释。

    提供背景上下文有助于新手将主题与他们已经知道的事物联系起来。

  • 参考指南包含 API 的技术参考。它们描述了 TLJH 内部机制的功能并指导其使用。

    保持参考资料紧密围绕主题。假设读者已经理解所涉及的基本概念,但需要了解或被提醒 TLJH 是如何实现的。

    参考指南不是进行一般性解释的地方。如果您发现自己正在解释基本概念,您可能需要将该材料移至主题指南。

  • 操作指南是分步指导读者完成关键主题的食谱。

    操作指南中最重要的内容是用户想要实现的目标。操作指南应该始终以结果为导向,而不是侧重于 TLJH 如何实现所讨论内容的内部细节。

    这些指南比教程更高级,并假设对 TLJH 的工作原理有所了解。假设读者已经学习了教程,并且不要犹豫将读者引导回相应的教程,而不是重复相同的内容。

  • 故障排除指南帮助读者回答“我的 JupyterHub 为什么不工作?”的问题。

    这些指南帮助读者尝试找出症状的原因,并希望解决问题。其中一些需要特定于云提供商,这是可以接受的。

写作风格#

通常,文档以第二人称书写,将读者称为“你”。在指代假设人物时使用代词,例如“一个正在运行 notebook 的用户”,应使用中性代词(they/their/them)。而不是

  • 他或她……使用他们。

  • 他或她……使用他们。

  • 他或她……使用他们的。

  • 他或她……使用他们的。

  • 他自己或她自己……使用他们自己。

常用术语#

以下是文档中常用术语的一些风格指南

  • TLJH – The Littlest JupyterHub 的常用缩写。除在代码/命令行中使用外,全部大写。

  • Python – 指代语言时,大写 Python。

  • Notebook 界面 – 指代 JupyterLab、经典 Notebook 和其他访问用户界面的通用术语。

Markdown 文件指南#

这些指南规范了我们的 Markdown 文档的格式

  • 在章节标题中,只大写首字母和专有名词。

  • 在句子中断处或大约 120 个字符宽处换行文档,除非代码示例在分成两行时可读性显著降低,或者有其他充分理由。

记录新功能#

我们对新功能的政策是

所有新功能在合并之前都必须有适当的文档。

选择图片大小#

向文档添加图片时,尽量保持图片尽可能小。较大的图片会使网站在浏览器上加载速度变慢,并可能使网速较慢的用户无法访问网站。

如果您要添加屏幕截图,请尽可能缩小截图尺寸。如果您要上传大图片,请考虑使用图片优化器来减小其尺寸。

例如,对于 PNG 文件,使用 OptiPNG 和 AdvanceCOMP 的 advpng

$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`

这基于 OptiPNG 版本 0.7.5。旧版本可能会抱怨 --strip all 选项会造成损失。

拼写检查#

在提交文档之前,最好运行拼写检查器。您需要先安装几个包

然后从 docs 目录运行 make spelling。错误单词(如果有)及其所在的文件和行号将保存到 _build/spelling/output.txt

如果您遇到误报(实际上是正确的错误输出),请执行以下操作之一

  • 用重音符 (`) 包裹内联代码或品牌/技术名称。

  • 查找拼写检查器能识别的同义词。

  • 如果,并且只有在您确定您使用的单词是正确的情况下,才将其添加到 docs/spelling_wordlist(请保持列表按字母顺序排列)。