开发环境设置#

本设置指南假设 python 命令引用的是 Python 3.7 或更高版本。我们推荐使用 pyenv 来管理 Python 版本。

克隆此包后，请运行以下命令：

./dev_setup.sh
pip install -e .[dev]

# if you use zsh you might need to escape `[` and `]`
pip install -e ".[dev]"

这将使用 pip 安装所有必需的包，并设置一个 Git hook，当您尝试创建新的 Git commit 时，它会自动进行类型和风格检查。

当您在分支上创建 commit 时，可以使用 --no-verify Git commit 选项暂时禁用这些检查。

构建说明#

运行项目测试：

pytest
# or
python setup.py tests

构建项目文档：

python setup.py docs

这会将文档放在 docs/_build/html 目录中，您可以通过打开 index.html 文件进行查看。

您也可以使用 setup.py 手动运行代码质量检查：

python setup.py type_check   # for Mypy type checks
python setup.py style_check  # for Black code style checks

请注意，上述命令是 build 命令的一部分，会自动执行。因此，希望将代码更改合并到项目主线的开发人员应确保其提交不违反上述命令。如果您已使用 ./dev_setup.sh 配置了开发环境并且没有依赖 --no-verify 选项，则在创建提交时应该已经强制执行了此检查。

编写类型安全的代码#

代码库广泛使用了类型提示。使用类型的好处是双重的。一方面，为方法和函数的参数和返回值添加类型提示提供了额外的元信息层，提高了代码的可读性。另一方面，借助像mypy这样的外部类型检查器，我们可以静态地捕获一些可能导致生产环境中出现 bug 的边缘情况。

如上所述，为了实现后者，构建工具链会执行 type_check 命令。但请注意，由于 mypy 检查目前报告了大量的类型错误，目前并非所有包都进行了类型检查。在我们完成现有包的迁移之前，建议开发人员遵循以下准则，以确保添加到代码仓库中的代码是类型安全的并经过类型检查。

在每个新包中添加一个名为 .typesafe 的空文件。确保测试包中也添加了标记文件。如果父包已经被标记为 .typesafe，则可以省略此文件。
确保为每个新方法和函数的参数和返回值提供正确的类型注解。这也适用于 void 方法和函数，以及 __init__ 方法，这些方法应标记返回类型为 None。

如果您遵循上述准则，您应该能够在您的分支上直接运行 python setup.py style_check 并尽早捕获类型错误。

编辑文档#

GluonTS 文档遵循NumPy docstring 格式。

如果您正在编辑源代码中的 docstring，可以使用以下命令预览它们：

make -C docs html                # generate the docs
open docs/_build/html/index.html # open the generated docs in a browser

在提交 PR 之前，请确保没有语法错误和警告。

使用just，您可以：

使用 just docs 构建整个文档，或者
仅将模板（如教程）翻译成 .md 文件，使用 just compile_notebooks skip。

如果您直接编辑 docs 文件夹中的 *.rst 文件，可以使用 sphinx-autobuild 自动构建会话，该会话会启动一个 Web 服务器和一个监视器，当您更改 *.rst 文件时会自动重新构建文档：

cd docs                          # go to the docs folder
make livehtml                    # run the autobuild watchdog, ensure that
                                 # there are no syntax errors and warnings
open http://127.0.0.1:8000       # open the autobuild preview

以下是一些总结 Sphinx 语法的有用链接：