Development Setup#

This setup guide assumes that you have Python 3.10 or higher installed. We recommend using uv for managing Python environments and dependencies.

Initial Setup#

Upon checking out this package, please run the following:

./dev_setup.sh

# Install with uv (recommended)
uv sync

This will install all required packages and setup a Git hook that does automated type and style checks when you try to create a new Git commit.

When you create commits on a branch, you can disable these checks temporarily with the --no-verify Git commit option.

Build Instructions#

To run the project tests:

uv run pytest

To build the project documentation, you can use just:

just docs

This will put the documentation in docs/_build/html, where you can inspect it by opening index.html.

You can also run the code quality checks manually:

uv run mypy src                        # type checking
uv run ruff format --check src test    # format checking
uv run ruff check src test             # linting
uv run python .devtools/license check src test  # license header checks

Note that these checks are executed automatically as part of CI. Developers that want to merge their code changes in the project mainline are therefore advised to ensure that their commits do not violate the above commands. If you have configured your developer environment using ./dev_setup.sh and are not relying on the --no-verify option, this should already be asserted when you create your commits.

Writing Type-Safe Code#

The codebase makes extensive use of type hints. The benefits of using types are twofold. On the one hand, typing the arguments and the return type of methods and functions provides additional layer of meta-information and improves the readability of the code. On the other, with the help of an external type-checker such as mypy we can statically catch a number of corner cases that can possibly cause bugs in production.

As explained above, in order to implement the latter, the type_check command is executed by the build toolchain. However, note that due to the large number of type errors currently reported by the mypy check, at the moment not all packages are type-checked. Until we finish the migration of existing packages, developers are advised to implement the following guidelines in order to ensure that code added to the repository is type-safe and type-checked.

  1. Add an empty file called .typesafe to each new package. Make sure that the marker files are added to test packages as well. You may omit this file if an ancestor package already is marked as .typesafe.

  2. Make sure that you provide proper type annotations for the parameters and the return type of every new method and function. This also applies to void method and functions as well as __init__ methods, which should be marked with return type None.

If you adhere to the above guidelines, you should be able to run uv run mypy src and catch type errors early directly on your branch.

Editing the documentation#

GluonTS documentation follows the NumPy docstring format.

If you are editing docstrings in source code, you can preview them with the following commands:

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

Ensure that there are no syntax errors and warnings before committing a PR.

If you are directly editing *.rst files within the docs folder, you can use a sphinx-autobuild autobuild session that starts a web server and a watchdog that automatically rebuilds the documentation when you change an *.rst file:

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

Here are some useful links summarizing the Sphinx syntax: