Using
=====

Jinks can be called through the :code:`jinks` command and requires a YAML configuration file

.. code-block:: shell

    jinks <configuration_file.yaml>


YAML Configuration file
"""""""""""""""""""""""

A jinks configuration file typically looks like this

.. code-block:: yaml

    device: raspberry_pi
    display: epd7in5_v2

    orientation: vertical
    invert: false

    refresh: 5m
    partial_refresh: 1m  # optional

    widgets:  # list of widgets
      - date_number:
          position:
            x: 0
            y: 0

      - week_day:
          position:
            x: 3
            y: 0

      - time:
          position:
            x: 3
            y: 2

Widgets have two main components, their **data** and their **display**
Jinks executes these separately in order to be able to run one data call for multiple widgets
(this can be done using the :code:`group_data` feature).

In practise this would look as the following

.. code-block:: yaml

      - weather_icon:
          position:
            x: 9
            y: 0
          data_group: weather_group
          data_group_master: true  # Makes the data request
          data_interval: 5m
          data:
            token: <weather.io token>
            location: <weather.io location>

      - weather_large:
          position:
            x: 0
            y: 5
          data_group: weather_group  # Gets data from master
          display:
            timestamps: 8


The :code:`data` section gives directly the arguments to the widget :code:`data` method
and the same goes for the :code:`display` which generates the widget image.
Jinks provides additional optional arguments to widget methods, see :ref:`developing`.

Sentry
""""""

Additionally if you with to know when errors are encountered on your display,
Sentry reporting has been implemented.

Simply install the :code:`sentry-sdk` package using :code:`pip install sentry-sdk`.
And add to the root of your configuration file at least :code:`sentry_dsn`

.. code-block:: yaml

    device: ...
    display: ...

    ...

    sentry_dsn: <dsn address>
    sentry_env: <environment>  # optional, default None
    sentry_release: <release>  # optional, default None