pyurbantz/docs/contributing.rst

Contributing
============

Contributions to the project are greatly appreciated.

Bugs and suggestions
--------------------

You may `submit an issue`_ to GitLab to warn of any bugs, ask for new features,
or ask any questions that are not answered in this documentation.

When reporting a bug, do not forget to put in your version of Python and your
version of *pyurbantz*. This will greatly help when troubleshooting, as most
errors often come from version incompatibilities.

Development
-----------

Setup
^^^^^

You will need a virtual envionment to work properly. `virtualenvwrapper`_ is
recommended::

   git clone https://gitlab.com/Lucidiot/pyurbantz
   cd pyurbantz
   mkvirtualenv -a . pyurbantz
   pip install -e .[dev]

This will clone the repository, create a virtual environment named
``pyurbantz``, then tell pip to let the package be editable (``-e``).
The ``[dev]`` suffix adds the extra requirements useful for development.

Unit tests
^^^^^^^^^^

Unit tests use the standard ``unittest`` package; you may run them using the
standard ``setup.py`` command::

   ./setup.py test

Tests coverage
^^^^^^^^^^^^^^

I aim for 100% coverage on all of my Python packages whenever I add unit
tests to them; this package is no exception. CI checks use the `coverage`_
Python package and `codecov`_ to check for test coverage. To get test coverage
data locally, run::

   coverage run setup.py test

You may then get a short coverage summary in your terminal::

   coverage report

Or generate an HTML report in a ``htmlcov`` folder, which can be browsed
offline using your favorite web browser and shows line by line coverage::

   coverage html

If you are having issues reaching 100% coverage, try to still add some tests,
and mention your issues when creating a pull request to the
`GitLab repository`_.

Linting
^^^^^^^

The source code follows the PEP 8 code style and performs CI checks using the
``flake8`` tool. To perform the same checks locally, run ``flake8`` on the root
directory of this repository.

Documentation
-------------

The documentation you are reading is generated by the `Sphinx`_ tool.
The text files that hold the documentation's contents are written in
`reStructuredText`_ and are available under the ``/docs`` folder of the
`GitLab repository`_.
They are also subject to linting using the ``doc8`` tool.

.. _submit an issue: https://gitlab.com/Lucidiot/pyurbantz/issues/new
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io
.. _coverage: https://coverage.readthedocs.io/
.. _codecov: https://codecov.io/gl/Lucidiot/pyurbantz
.. _GitLab repository: https://gitlab.com/Lucidiot/pyurbantz
.. _Sphinx: http://www.sphinx-doc.org/
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html