b284ace102
Fix #195: Add mypy test in .github/workflows/docs_and_lint.yml. Also remove the out-of-the-date api
113 lines
2.6 KiB
ReStructuredText
113 lines
2.6 KiB
ReStructuredText
Contributing to Tianshou
|
|
========================
|
|
|
|
|
|
Install Develop Version
|
|
-----------------------
|
|
|
|
To install Tianshou in an "editable" mode, run
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install -e ".[dev]"
|
|
|
|
in the main directory. This installation is removable by
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python setup.py develop --uninstall
|
|
|
|
|
|
PEP8 Code Style Check
|
|
---------------------
|
|
|
|
We follow PEP8 python code style. To check, in the main directory, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ flake8 . --count --show-source --statistics
|
|
|
|
|
|
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
|
|
|
|
$ mypy
|
|
|
|
|
|
Test Locally
|
|
------------
|
|
|
|
This command will run automatic tests in the main directory
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pytest test --cov tianshou -s --durations 0 -v
|
|
|
|
|
|
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 webpages, run
|
|
|
|
.. code-block:: bash
|
|
|
|
$ make html
|
|
|
|
under the ``docs/`` directory. The generated webpages are in ``docs/_build`` and can be viewed with browsers.
|
|
|
|
Chinese documentation is in https://tianshou.readthedocs.io/zh/latest/.
|
|
|
|
|
|
Documentation Generation Test
|
|
-----------------------------
|
|
|
|
We have the following three documentation tests:
|
|
|
|
1. pydocstyle: test docstrings under ``tianshou/``. To check, in the main directory, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pydocstyle tianshou
|
|
|
|
2. doc8: test ReStructuredText formats. To check, in the main directory, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ doc8 docs
|
|
|
|
3. sphinx test: test if there is any errors/warnings when generating front-end html documentations. To check, in the main directory, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cd docs
|
|
$ make html SPHINXOPTS="-W"
|