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

Contributions to the project are greatly appreciated.

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

You may `submit an issue`_ to the Gitea repository 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 *pylspci*. 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://tildegit.org/lucidiot/pylspci.git
   cd pylspci
   mkvirtualenv -a . pylspci
   pip install -e .[dev]

This will clone the repository, create a virtual environment named
``pylspci``, 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 to get coverage statistics.
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
`Gitea 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.

Type checking
^^^^^^^^^^^^^

The source code uses PEP 484 type hints and type checking is performed in CI
using ``mypy``. To run those checks locally, run ``mypy .`` 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
`Gitea repository`_.
They are also subject to linting using the ``doc8`` tool.

.. _submit an issue: https://tildegit.org/lucidiot/pylspci/issues/new
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io
.. _coverage: https://coverage.readthedocs.io/
.. _Gitea repository: https://tildegit.org/lucidiot/pylspci
.. _Sphinx: http://www.sphinx-doc.org/
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html