建筑文件¶
在对 BeeWare 的文档进行任何更改之前，最好先确认您可以构建现有文档。
在构建文档之前，请确保已设置好开发环境。
你必须在你的 PATH 上安装 Python 3.13 解释器，并确保它可用（即确保 python3.13 可以启动 Python 3.13 解释器）。
BeeWare 使用 tox 构建文档。以下 tox 命令必须在与 tox.ini 文件相同的位置运行，也就是在项目的根目录下。
实时文档预览¶
为支持文档的快速编辑，BeeWare 文档具有“实时预览”模式。
实时预览构建不受警告影响！
实时预览服务器可用于迭代文档更改。在更改过程中，你可能会引入标记问题。被视为 WARNING 的问题会导致标准构建失败，但实时预览服务器只会在控制台输出中显示警告，并同时继续构建。这样，你可以继续进行迭代，而无需重新启动实时预览。
WARNING 不同于 ERROR。如果你引入了一个 ERROR 类问题，实时预览服务器就会失败，需要重新启动。在 WARNING 问题解决之前，它无法被重新启动。
启动实时服务器：
(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 目录中。
运行文档 lint¶
构建过程会识别 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"）。
- 如果一个术语被“作为代码”使用，那么它就应该作为字面格式（
像这样）被引用，而不是被添加到拼写词典中。
成功构建文档后，您就可以开始编写文档了。