Dev How-to
===================

Coding Guidelines
-------------------

LogML coding guide is based on `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_,
adjusting it when needed.

Lint
^^^^^^^

LogML provides :code:`.pylintrc` file in the base of its repository, which contains set of default
rules and exceptions for LogML.

Pylint is installed into `logml` conda environment.

Command to run locally:

.. code-block:: bash

    python -m pylint --output-format=parseable \
                            --fail-under=9.75 \
                            --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" \
                            ./src \
                            | tee pylint.log || echo "pylint exited with \$?"





Coding style
^^^^^^^^^^^^^^^^

Test width is 100 (preferred), 120 (max) symbols.


Dependencies
^^^^^^^^^^^^^^^

  - Put all EligibleXXX items into one package, single level.
  - Use `import_submodules` in the package __init__.py file to import modules at a single level.
  - Everywhere: defer importing all EligibleXXX items, due to the fact
    that they perform blanket-style import and can import half of the application along.


Unit Testing
-----------------

Always run `./scripts/run_tests.sh` and make sure all the tests are green prior to pushing your changes to the repository.

External Dependency Management
---------------------------------

Please update `./environment.yaml` each time you install and import a new package.

Exact package version should always be specified (e.g. `gensim=3.4.0`).

Config schema updates
---------------------

When working with config, it can be hard to detect exact changes in schema.
To make this task easier, we store latest config schema in git, so we can track it.

Invoke the command to generate schema before creating PR:

.. code-block:: bash

    python log_ml.py config print-schema -o schema/logml_config_schema.yaml

Build Sphinx documentation
---------------------------

Having logml conda environment active, open `docs` folder, and use the following command:

.. code-block:: bash

     rm -r pages/dev/generated_refs/* && make clean && make html

to rebuild documentation from scratch. (or just `make html` to make incremental build).

Entry point is `docs/_build/html/index.html`.