编写文档#

注意

我们高度重视文档的一致性、可读性和完整性。如果一个功能没有文档，它就不存在。如果一个行为没有文档，它就是一个错误！我们试图像对待代码一样对待我们的文档：我们力求尽可能频繁地改进它。

文档更改通常有两种形式

一般改进：拼写错误更正、错误修复以及通过更清晰的写作和更多示例来改进解释。
新功能：自上次发布以来添加到框架中的功能的文档。

本节说明编写者如何以最有用且最不容易出错的方式来编写他们的文档更改。

获取原始文档#

虽然 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 无法正常工作？”的问题。

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

写作风格#

通常，文档以第二人称写作，将读者称为“你”。当使用代词来指代假设的人时，例如“拥有正在运行的笔记本的用户”，应该使用中性代词（他们/他们的/他们）。而不是

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

常用术语#

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

TLJH – The Littlest JupyterHub 的常用缩写。除了在代码/命令行中使用时，其他情况都大写。
Python – 当指代语言时，将 Python 大写。
笔记本界面 – 指代 JupyterLab、经典笔记本和其他用于访问的用户界面的通用术语。

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 中（请保持列表按字母顺序排列）。