Tianshou/docs/04_contributing/04_contributing.rst

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