2cc34fb72b
Closes #914 Additional changes: - Deprecate python below 11 - Remove 3rd party and throughput tests. This simplifies install and test pipeline - Remove gym compatibility and shimmy - Format with 3.11 conventions. In particular, add `zip(..., strict=True/False)` where possible Since the additional tests and gym were complicating the CI pipeline (flaky and dist-dependent), it didn't make sense to work on fixing the current tests in this PR to then just delete them in the next one. So this PR changes the build and removes these tests at the same time.
115 lines
2.8 KiB
ReStructuredText
115 lines
2.8 KiB
ReStructuredText
Contributing to Tianshou
|
|
========================
|
|
|
|
|
|
Install Develop Version
|
|
-----------------------
|
|
|
|
Tianshou is built and managed by `poetry <https://python-poetry.org/>`_. For example,
|
|
to install all relevant requirements in editable mode you can simply call
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poetry install --with dev
|
|
|
|
|
|
PEP8 Code Style Check and Formatting
|
|
----------------------------------------
|
|
|
|
Please set up pre-commit by running
|
|
|
|
.. code-block:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poe format
|
|
$ poe lint
|
|
|
|
|
|
Type Check
|
|
----------
|
|
|
|
We use `mypy <https://github.com/python/mypy/>`_ to check the type annotations. To check, in the main directory, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poe type-check
|
|
|
|
|
|
Test Locally
|
|
------------
|
|
|
|
This command will run automatic tests in the main directory
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poe test
|
|
|
|
|
|
Test by GitHub Actions
|
|
----------------------
|
|
|
|
1. Click the ``Actions`` button in your own repo:
|
|
|
|
.. image:: _static/images/action1.jpg
|
|
:align: center
|
|
|
|
2. Click the green button:
|
|
|
|
.. image:: _static/images/action2.jpg
|
|
:align: center
|
|
|
|
3. You will see ``Actions Enabled.`` on the top of html page.
|
|
|
|
4. When you push a new commit to your own repo (e.g. ``git push``), it will automatically run the test in this page:
|
|
|
|
.. image:: _static/images/action3.png
|
|
:align: center
|
|
|
|
|
|
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 <https://pythonhosted.org/an_example_pypi_project/sphinx.html>`_.
|
|
|
|
API References are automatically generated by `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ according to the outlines under ``docs/api/`` and should be modified when any code changes.
|
|
|
|
To compile documentation into webpage, run
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poe doc-build
|
|
|
|
The generated webpage is in ``docs/_build`` and can be viewed with browser (http://0.0.0.0:8000/).
|
|
|
|
Chinese documentation is in https://tianshou.readthedocs.io/zh/latest/.
|
|
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ poe lint
|
|
$ poe doc-build
|