Contributing to Tianshou#

Install Develop Version#

Tianshou is built and managed by poetry. For example, to install all relevant requirements in editable mode you can simply call

$ poetry install --with dev

Platform-Specific Configuration#

Windows: Since the repository contains symbolic links, make sure this is supported:

  • Enable Windows Developer Mode to allow symbolic links to be created: Search Start Menu for “Developer Settings” and enable “Developer Mode”

  • Enable symbolic links for this repository: git config core.symlinks true

  • Re-checkout the current git state: git checkout .

PEP8 Code Style Check and Formatting#

Please set up pre-commit by running

$ pre-commit install

in the main directory. This should make sure that your contribution is properly formatted before every commit.

The code is inspected and formatted by black and ruff. They are executed as pre-commit hooks. In addition, poe the poet tasks are configured. Simply run poe to see the available tasks. E.g, to format and check the linting manually you can run:

$ poe format
$ poe lint

Type Check#

We use mypy to check the type annotations. To check, in the main directory, run:

$ poe type-check

Test Locally#

This command will run automatic tests in the main directory

$ poe test

Test by GitHub Actions#

  1. Click the Actions button in your own repo:

../_images/action1.jpg

  1. Click the green button:

../_images/action2.jpg

  1. You will see Actions Enabled. on the top of html page.

  2. When you push a new commit to your own repo (e.g. git push), it will automatically run the test in this page:

../_images/action3.png

Documentation#

Documentations are written under the docs/ directory as ReStructuredText (.rst) files. index.rst is the main page. A Tutorial on ReStructuredText can be found here.

API References are automatically generated by Sphinx according to the outlines under docs/api/ and should be modified when any code changes.

To compile documentation into webpage, run

$ poe doc-build

The generated webpage is in docs/_build and can be viewed with browser (http://0.0.0.0:8000/).

Documentation Generation Test#

We have the following three documentation tests:

  1. pydocstyle (as part of ruff): test all docstring under tianshou/;

  2. doc8 (as part of ruff): test ReStructuredText format;

  3. sphinx spelling and test: test if there is any error/warning when generating front-end html documentation.

To check, in the main directory, run:

$ poe lint
$ poe doc-build