建筑文件¶
在对 BeeWare 的文档进行任何更改之前，最好先确认您可以构建现有文档。
在构建文档之前，请确保已设置好开发环境。
您必须***在您的路径上安装了 Python 3.13 解释器并可用（即 python3.13 必须启动 Python 3.13 解释器）。
BeeWare 使用 tox 构建文档。以下 tox 命令必须在与 tox.ini 文件相同的位置运行，也就是在项目的根目录下。
实时文档预览¶
为支持文档的快速编辑，BeeWare 具有 "实时预览 "模式。
实时预览将带警告构建！
实时服务可用于迭代文档更新。在更新过程中，可能会引入标记问题。被视为 "警告 "的问题会导致标准构建失败，但实时服务会在控制台输出中显示警告，同时继续构建。这样，您就可以进行迭代，而无需重新启动实时预览。
警告 "不同于 "错误"。如果引入了一个被认为是 "错误 "的问题，实时服务就会失败，需要重新启动。在警告问题解决之前，它不会再次启动。
启动实时服务器：
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
这将构建文档，启动网络服务器为文档提供服务，并监视文件系统是否对文档源进行了任何更改。
服务器启动后，你会在控制台输出中看到类似下面的内容：
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
打开浏览器，导航到提供的 URL。现在你可以开始迭代文档了。如果检测到更改，文档将被重建，任何查看修改后页面的浏览器都将自动刷新。
docs-live 只是第一步
运行 "docs-live "来使用实时服务器是为了进行初始迭代。在提交拉取请求之前，您应该**运行本地构建。
本地构建¶
完成迭代后，您需要对文档进行本地构建。如果出现任何标记问题，这个构建过程就会失败。这样，您就可以捕捉到在实时服务器上可能遗漏的任何内容。
生成本地构建¶
若想要生成本地构建：
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
编译的输出结果将保存在项目根目录下的 _build 目录中。
生成本地翻译版本¶
BeeWare 的文档被翻译成多种语言。英文文档的更新有可能导致其他语言版本出现问题。在提交拉取请求之前，请务必确认所有版本都能正常运行。
生成所有可用翻译的构建文件：
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
每种语言编译的输出结果将保存在相关的 _build/html/<languagecode>目录中，其中
<languagecode>是与特定语言相关的两个或五个字符的语言代码（例如 fr 表示法语，it 表示意大利语等）。
如果您发现单个编译存在问题，可以运行 tox -e docs-<languagecode> 单独运行该单个编译。例如，要只编译法语文档，请运行：
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
单语言编译的输出将位于 _build 目录中。
文件整理¶
构建过程会识别 Markdown 问题，但 BeeWare 还会执行一些额外的样式和格式检查，即所谓的 "linting"。要运行 "linting "检查:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
这将验证文件是否包含：
- 死超链接
- 错别字
如果一个单词的有效拼写被识别为拼写错误，则将该单词添加到 docs/spelling_wordlist
中的列表中。这将把该词添加到拼写检查程序的词典中。添加到该列表时，请记住：
- 我们倾向于使用美式拼写法，但对程序特定的口语（如 "apps"）和名词的动词化（如 "scrollable"）有一定的自由度
- 任何对产品名称的引用都应使用该产品的首选大写字母。(例如，"macOS"、"GTK"、"pytest"、"Pygame"、"PyScript"）。
- 如果一个术语是 "作为代码 "使用的，那么它就应该作为字面意义（"像这样"）被引用，而不是被添加到词典中。
成功构建文档后，您就可以开始编写文档了。