开发环境设置#

本设置指南假设 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]"

这将安装所有必需的包，并设置一个 Git 钩子，在您尝试创建新的 Git 提交时进行自动类型和样式检查。

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

构建说明#

要运行项目测试：

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，我们可以静态地捕获潜在导致生产中出现错误的多种边缘情况。

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

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

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

编辑文档#

GluonTS 文档遵循 NumPy 文档字符串格式。

如果您正在源代码中编辑文档字符串，您可以使用以下命令预览它们：

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 自动构建会话，启动一个网络服务器和一个监视器，当您更改 *.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 语法：