撰写文档#

注意

我们高度重视文档的一致性、可读性和完整性。如果一个功能没有文档，那么它就不存在。如果一个行为没有文档，那么它就是一个 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:

要开始贡献，您需要熟悉 Markdown 和 MyST。

您本地构建的文档的主题将与 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 选项会造成损失。

拼写检查#

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

pyenchant（需要 enchant）
sphinxcontrib-spelling

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

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

用重音符 (`) 包裹内联代码或品牌/技术名称。
查找拼写检查器能识别的同义词。
如果，并且只有在您确定您使用的单词是正确的情况下，才将其添加到 docs/spelling_wordlist（请保持列表按字母顺序排列）。