.. _development:

###########
Development
###########

.. _development-debugging:

Debugging
=========

Set log level to ``info`` or ``debug`` to get more verbose output:

.. code-block:: bash

    hods --log-level=info

The log file is placed in your .hods directory: ``~/.hods/log``.

.. note:: If your ``.hods/`` directory doesn't exist yet, *hods* will log to the terminal instead!


.. _development-invoke:

invoke
======

*hods* uses ``pyinvoke`` as entrypoint for most development tasks which may install additional
packages into the currently active interpreter environment. The provided tasks do **NOT** check
the environment for an active *virtualenv*! Make sure you're using the correct interpreter.
Creation of a **virtualenv** is *highly recommended*!

Install ``invoke`` using ``pip``::

   pip install invoke

List available tasks::

   inv -l


.. _development-tests:

Tests
=====

Use the ``test`` task to install and run *tox*::

   inv test

This will install and run ``tox`` to run the tests against all available python interpreters.

For more information on *tox* visit: https://tox.readthedocs.io/


.. _development-tests-dependencies:

Testing dependency versions
---------------------------

The test-suite is also run against all active versions of all library dependencies!

Some distributions like debian treat software libraries as distribution packages. Pinning a
dependency (using ``==<version>`` in requirements) leads to errors or additional work for the
end-user in these environments. The software should work with these slightly older but still active
versions! That's what deprecations are for.

*hods* aims to run with the distribution packages on debian *oldstable* and above. This means:

*  Don't use a new library feature until the version it first appeared in has reached *oldstable*.

*  Remove usage of a library feature ASAP. E.g. when its deprecated or when it has been removed in
   *testing* or *sid*.

*  Support all active versions when in doubt. Code is supposed to be smart.


.. _development-tests-variables:

Environment Variables
---------------------

+-----------------------+---------+---------+----------------------------------+
| Variable              | Default | Example | Description                      |
+=======================+=========+=========+==================================+
| HODS_DEFER_MULTIPLIER | 1       | 1.5     | increase on slow hosts (<800Mhz) |
+-----------------------+---------+---------+----------------------------------+
| HODS_SCREENSHOTS      | 0       | 1       | Create documentation screenshots |
+-----------------------+---------+---------+----------------------------------+
| CHROME_HEADLESS       | 0       | 1       | Run chrome in headless mode      |
+-----------------------+---------+---------+----------------------------------+


.. _development-lint:

lint
====

The *tox* test matrix also runs the *flake8* linter. Use the ``lint`` task to start it standalone::

   inv lint


.. _development-documentation:

Documentation
=============

Run the ``docs`` task to render the documentation::

   inv docs


Use the ``-s`` (or ``--screenshots``) flag to create all screenshots before rendering
the documentation::

   inv docs -s

The ``-b <browser>`` (or ``--browser <browser>``) flag opens it in the given browser::

   inv docs -b firefox