Skip to content

Commit

Permalink
Update contribution guidelines (#58)
Browse files Browse the repository at this point in the history
Adds some information about running local tests, generating local code coverage and making sure new code is PEP8 compliant.
  • Loading branch information
purva-thakre committed Jun 16, 2021
1 parent 1603af5 commit fa1cb1b
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 5 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,12 @@ If you want to edit the source code, please download the source code and run the
pip install --upgrade pip
pip install -e .
```
which makes sure that you are up to date with the latest `pip` version.
which makes sure that you are up to date with the latest `pip` version. Contribution guidelines are available [*here*](https://qutip-qip.readthedocs.io/en/latest/contribution-code.html).

To build and test the documentation, additional packages need to be installed:

```
pip install matplotlib sphinx numpydoc sphinx_rtd_theme
pip install pytest matplotlib sphinx numpydoc sphinx_rtd_theme
```

Under the `doc` directory, use
Expand Down
79 changes: 76 additions & 3 deletions doc/source/contribution-code.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ Contributing to the source code
Build up an development environment
===================================

Please follow the instruction on the `QuTiP contribution guide <https://qutip.org/docs/latest/development/contributing.html#building>`_ to
Please follow the instruction on the `QuTiP contribution guide <https://qutip.org/docs/latest/development/contributing.html#building>`_ to
build a conda environment.
You don't need to build `qutip` in the editable mode unless you also want to contribute to `qutip`.
Instead, you need to install qutip-qip by downloading the source code and run
You don't need to build ``qutip`` in the editable mode unless you also want to contribute to `qutip`.
Instead, you need to install ``qutip-qip`` by downloading the source code and run

.. code-block:: bash
Expand All @@ -24,3 +24,76 @@ explaining the functionality, including input parameters and returned values.
The docstring should follow
`NumPy Style Python Docstrings <https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html>`_.

Checking Code Style and Format
==============================

In order to check if your code in ``some_file.py`` follows `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
style guidelines, `Black <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_
has to be installed.

.. code-block::
pip install black
In the directory that contains ``some_file.py``, use

.. code-block::
black some_file.py --check
black some_file.py --diff --color
black some_file.py
Using ``--check`` will show if any of the file will be reformatted or not.

* `Code 0 <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#the-basics>`_ means nothing will be reformatted.
* Code 1 means one or more files could be reformatted. More than one files could
be reformatted if ``black some_directory --check`` is used.

Using ``--diff --color`` will show a `difference <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#diffs>`_ of
the changes that will be made by ``Black``. If you would prefer these changes to be made, use the last line of above code block.

.. note::
We are currently in the process of checking format of existing code in ``qutip-qip``.
Running ``black existing_file.py`` will attempt to format existing code. We
advise you to create a separate issue for ``existing_file.py`` or skip re-formatting
``existing_file.py`` in the same PR as your new contribution.

It is advised to keep your new contribution ``PEP8`` compliant.

Checking tests locally
=======================

You can run tests and generate code coverage report locally. First make sure
required packages have been installed.

.. code-block::
pip install pytest pytest-cov
``pytest`` is used to test files containing tests. If you would like to test all the
files contained in a directory then specify the path to this directory. In order to run
tests in ``test_something.py`` then specify the exact path to this file for ``pytest``
or navigate to the file before running the tests.

.. code-block::
pytest path_to_some_directory
pytest /path_to_test_something/test_something.py
~/path_to_test_something$ pytest test_something.py
A code coverage report in ``html`` format can be generated locally for
``qutip-qip`` using the code line given below. By default the coverage report
is generated in a temporary directory ``htmlcov``. The report can be output
in `other formats <https://pytest-cov.readthedocs.io/en/latest/reporting.html>`_
besides ``html``.

.. code-block::
pytest --cov-report html --cov=qutip_qip tests/
If you would prefer to check the code coverage of one specific file, specify
the location of this file. Same as above the report can be accessed in ``htmlcov``.

.. code-block::
pytest --cov-report html --cov=qutip_qip tests/test_something.py

0 comments on commit fa1cb1b

Please sign in to comment.