这些源文件采用 restructured text 格式，旨在使用 Sphinx 文档生成器（http://sphinx.pocoo.org/）编译为独立的 HTML 文档 （有时为 PDF）。
请参阅 requirements.txt 以获取构建文档所需的 python 依赖项。
部分源文件引用了 invest-sample-data 仓库中的表格。
在构建文档之前，必须在当前仓库的顶层存在 invest-sample-data 的克隆。
执行以下命令以克隆 invest-sample-data 并检出正确的修订版本：
make invest-sample-data
执行以下命令，从 reStructuredText 源文件构建 HTML 文档：
make html
然后在 build/html 中找到 html 文档，并在 web browser 中查看它们以评估其正确性。
Branching & Development Guidelines
对 InVEST 当前已发布版本的 User Guide 的编辑可以直接在此 repo 的 main 分支上进行。
对 InVEST 尚未发布的功能的编辑应在此 repo 中对应的 release/X.X 分支上进行。该分支应在对应的 invest 发布时同时合并到 main。
Style Guidelines
我们的 style guide google doc 正在积极开发中。 对于我们的 style guide 中未列出的任何内容，请遵循 Google developer documentation style guidelines。
Requirements
requirements.txt 是构建 user's guide 所需的完整 requirements 列表。
然而，pip install -r requirements.txt 将在一个全新的环境中失败，因为 natcap.invest 依赖于 gdal，除非系统中已经存在 GDAL 库和 headers，否则无法进行 pip install。
由于 GDAL 库和 headers 可以通过 conda 安装，因此包含了一个 environment.yml，它将使用 conda 安装 GDAL，然后使用 pip 安装其余的 requirements。
Internationalization
在常规编辑源 RST 文件时，无需执行任何特殊操作。有关更多背景信息，请参阅 InVEST internationalization README。
用户指南中有三个组成部分具有独立的翻译机制：源 RST 文件中的文本；由 Sphinx 提供的文本，例如 "Note" 或 "Warning"；以及通过自定义 :investspec: 角色从 natcap.invest 导入的文本。
以下所有命令都应从项目根目录运行，并且 <LANG> 应替换为相应的 ISO 639-1 语言代码。
如何更新某种语言的翻译
1. 更新源 RST 文本的翻译
运行 make gettext 以提取消息并创建新的 POT 文件。这使用 Sphinx gettext 构建器从每个文档节点中提取消息。这很好，因为它无需以任何方式修改源 RST 即可工作。每个源 RST 文件将有一个 POT 文件，它们将创建在 build/gettext 中。
从新的 POT 文件更新该语言的 PO 文件：
$ sphinx-intl update --locale-dir source/locales --pot-dir build/gettext --language <LANG>
或者更新所有语言的 PO 文件：
$ sphinx-intl update --locale-dir source/locales --pot-dir build/gettext
将 source/locales/<LANG>/LC_MESSAGES 中的 PO 文件发送给该语言的翻译人员。翻译人员将填写翻译并发送回来。
用翻译人员提供的更新版本替换 source/locales/<LANG>/LC_MESSAGES 中的 PO 文件。
2. 更新从 natcap.invest 导入的文本的翻译
更新 natcap.invest 中相关的翻译（参见 InVEST 国际化 README）。
如何添加新语言
1. 为源 RST 文本添加新语言
按照上述相同步骤 更新翻译。如果 sphinx-intl update 命令对应的语言尚不存在，它将创建该语言的新 PO 文件。
2. 为 Sphinx 提供的文本添加新语言
该语言很可能在 Sphinx 支持的语言列表 中，因此无需执行任何操作。但如果不在，我们需要弄清楚如何为 Sphinx 生成的消息提供自己的消息目录。
3. 为从 natcap.invest 导入的文本添加新语言
确保 natcap.invest 也支持该新语言（参见 InVEST 国际化 README）。
以其他语言构建文档
make SPHINXOPTS="-D language=<LANG>" html