rougail/docs/developer.rst

Developer notes
==========================

.. admonition:: team developer material

   This section is intended to be usefull for team developers only.


Quick installation process
---------------------------------------

This process describes how to install and run the project locally, e.g. for development purposes.

*Nota*: command is to be executed through the terminal

`pip install rougail`

Code quality
---------------

We are using `pre-commit <https://pre-commit.com/>`_, there is a :file:`.pre-commit-config.yaml`
pre-commit config file in the root's project.

You need to:

- install the pre-commit library::

    pip install pre-commit

- registrer the pre-commit git hooks with this command::

    pre-commit install

- launch the quality code procedure with::

    pre-commit

  or simply just commit your changes, pre-commit will automatically be launched.

.. attention:: If an error is found, the commit will not happen.
   You must resolve all errors that pre-commit that pre-commit points out to you before.

.. note:: If you need for some reason to disable `pre-commit`, just set
          the `PRE_COMMIT_ALLOW_NO_CONFIG` environment variable before commiting::

              PRE_COMMIT_ALLOW_NO_CONFIG=1 git commit

Coding standard
------------------

We use black

.. code-block:: yaml

  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black

And some YAML and JSON validators.


----

The pre commit tool
----------------------

**pre-commit** is a fantastic tool for automating code quality checks
before you commit your changes. It’s especially useful in Python
projects for running linters, formatters, and other checks
automatically.

Here’s a **practical, minimal example** to get you started with a small
Python project.


1. Install pre-commit
---------------------

First, install the ``pre-commit`` package:

.. code:: bash

   pip install pre-commit


2. Create a ``.pre-commit-config.yaml`` File
--------------------------------------------

In the root of your Python project, create a file named
``.pre-commit-config.yaml`` with the following content:

.. code:: yaml

   repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v4.4.0
       hooks:
         - id: trailing-whitespace
         - id: end-of-file-fixer
         - id: check-yaml
         - id: check-added-large-files

     - repo: https://github.com/psf/black
       rev: 23.12.1
       hooks:
         - id: black

     - repo: https://github.com/pycqa/flake8
       rev: 6.1.0
       hooks:
         - id: flake8

This config: - Uses popular pre-commit hooks for basic checks - Adds
`Black <https://github.com/psf/black>`__ for code formatting - Adds
`Flake8 <https://github.com/pycqa/flake8>`__ for linting


3. Install the Git Hook
-----------------------

Run this command in your project root:

.. code:: bash

   pre-commit install

This sets up a Git hook that runs the checks before each commit.


4. Try It Out
-------------

Now, when you try to commit:

.. code:: bash

   git add .
   git commit -m "My commit message"

pre-commit will run the hooks. If any check fails, you’ll see output
like this:

::

   Trim Trailing Whitespace............................................Passed
   Fix End of Files....................................................Passed
   Check Yaml..........................................................Passed
   Check for added large files..........................................Passed
   Black..............................................................Failed
   - hook id: black
   - exit code: 1

   Reformatted /path/to/your/file.py
   All done! ✨ 🍰 ✨
   1 file reformatted.

If any hook fails, fix the issues and try committing again.


5. (Optional) Run pre-commit Manually
-------------------------------------

You can run all hooks against all files at any time:

.. code:: bash

   pre-commit run --all-files


6. Update Hooks
---------------

To update your hooks to the latest versions:

.. code:: bash

   pre-commit autoupdate

**Summary Table**
~~~~~~~~~~~~~~~~~

==== ===================== ==============================
Step Action                Command
==== ===================== ==============================
1    Install pre-commit    ``pip install pre-commit``
2    Create config file    ``.pre-commit-config.yaml``
3    Install Git hook      ``pre-commit install``
4    Commit and see checks ``git commit -m "..."``
5    Run manually          ``pre-commit run --all-files``
6    Update hooks          ``pre-commit autoupdate``
==== ===================== ==============================

more python linters
-------------------

Customizing your ``.pre-commit-config.yaml`` to include **pylint**,
**ruff**, and additional hooks is a great way to maintain code quality.
Here’s how you can structure your config for a robust setup:

**1. Basic Setup with pylint and ruff**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here’s a starting point for your ``.pre-commit-config.yaml``:

.. code:: yaml

   repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v4.4.0
       hooks:
         - id: trailing-whitespace
         - id: end-of-file-fixer
         - id: check-yaml
         - id: check-added-large-files

     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.1.6
       hooks:
         - id: ruff
           args: [--fix, --exit-non-zero-on-fix]

     - repo: https://github.com/pycqa/pylint
       rev: v3.0.3
       hooks:
         - id: pylint
           args: [--rcfile=.pylintrc]  # Optional: specify a pylint config file

**2. Adding More Hooks**
~~~~~~~~~~~~~~~~~~~~~~~~

Here are some popular hooks you might want to add:

**a. Black (Code Formatter)**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: yaml

     - repo: https://github.com/psf/black
       rev: 23.12.1
       hooks:
         - id: black

**b. Mypy (Static Type Checker)**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: yaml

     - repo: https://github.com/pre-commit/mirrors-mypy
       rev: v1.8.0
       hooks:
         - id: mypy

**c. isort (Import Sorter)**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: yaml

     - repo: https://github.com/pycqa/isort
       rev: 5.13.2
       hooks:
         - id: isort

**d. Bandit (Security Linter)**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: yaml

     - repo: https://github.com/pycqa/bandit
       rev: 1.7.7
       hooks:
         - id: bandit

**3. Full Example Config**
~~~~~~~~~~~~~~~~~~~~~~~~~~

Here’s a full example with all the above hooks:

.. code:: yaml

   repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v4.4.0
       hooks:
         - id: trailing-whitespace
         - id: end-of-file-fixer
         - id: check-yaml
         - id: check-added-large-files

     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.1.6
       hooks:
         - id: ruff
           args: [--fix, --exit-non-zero-on-fix]

     - repo: https://github.com/pycqa/pylint
       rev: v3.0.3
       hooks:
         - id: pylint
           args: [--rcfile=.pylintrc]

     - repo: https://github.com/psf/black
       rev: 23.12.1
       hooks:
         - id: black

     - repo: https://github.com/pre-commit/mirrors-mypy
       rev: v1.8.0
       hooks:
         - id: mypy

     - repo: https://github.com/pycqa/isort
       rev: 5.13.2
       hooks:
         - id: isort

     - repo: https://github.com/pycqa/bandit
       rev: 1.7.7
       hooks:
         - id: bandit

**4. Customizing Hooks**
~~~~~~~~~~~~~~~~~~~~~~~~

-  **pylint**: You can specify a config file (``.pylintrc``) or pass
   arguments directly.
-  **ruff**: You can customize rules in ``pyproject.toml`` or
   ``.ruff.toml``.
-  **Black, isort, mypy**: Each can be configured via their respective
   config files.

**5. Installing and Running**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Save the config to ``.pre-commit-config.yaml``.

2. Run:

   .. code:: bash

      pre-commit install
      pre-commit run --all-files