Instructions
============

|hatch|
|pre-commit|
|ruff|
|black|
|doc8|
|mypy|
|pylint|
|slotscheck|

.. |hatch| image:: https://img.shields.io/badge/%F0%9F%A5%9A-hatch-4051b5.svg
   :target: https://pypi.org/project/hatch/
.. |pre-commit| image:: https://img.shields.io/badge/-pre--commit-brightgreen?logo=pre-commit&labelColor=gray
   :target: https://pypi.org/project/pre-commit/
.. |ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
   :target: https://pypi.org/project/ruff/
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://pypi.org/project/black/
.. |doc8| image:: https://img.shields.io/badge/static--checked-doc8-green
   :target: https://pypi.org/project/doc8/
.. |mypy| image:: https://img.shields.io/badge/static--checked-mypy-blue
   :target: https://pypi.org/project/mypy/
.. |pylint| image:: https://img.shields.io/badge/dynamic--checked-pylint-orange
   :target: https://pypi.org/project/pylint/
.. |slotscheck| image:: https://img.shields.io/badge/dynamic--checked-slotscheck-orange
   :target: https://pypi.org/project/slotscheck/

Prerequisite
------------

*galactic-helper-core* requires `python 3.11`_,
a programming language that comes pre-installed on linux and Mac OS X,
and which is easily installed `on Windows`_;

Installation
------------

First, install *galactic* in a virtual environment (``conda`` or ``venv``)
using the instructions given in
the `Quick start guide <https://www.thegalactic.org/start.html>`_.

Second, you can install *galactic-helper-core* in the same environment
using the bash command:

.. code-block:: shell-session

    (galactic) $ pip install galactic-helper-core

Don't forget to add the ``--pre`` flag if you want the latest unstable build.

If you want to verify package integrity using hashes, you can install
*galactic-helper-core* in the same environment with the following bash command:

.. code-block:: shell-session

    (galactic) $ pip install -r https://www.thegalactic.org/requirements/stable/galactic-helper-core.txt

and for the pre-release version with the following bash command:

.. code-block:: shell-session

    (galactic) $ pip install -r https://www.thegalactic.org/requirements/pre/galactic-helper-core.txt

Contributing
------------

Build
~~~~~

Building *galactic-helper-core* requires

* `hatch`_, which is a tool for dependency management and packaging in Python;

Build *galactic-helper-core* using the bash command

.. code-block:: shell-session

    $ hatch build

Testing
~~~~~~~

Test *galactic-helper-core* using the bash command:

.. code-block:: shell-session

    $ hatch test

for running the tests.

.. code-block:: shell-session

    $ hatch test --cover

for running the tests with the coverage.

.. code-block:: shell-session

    $ hatch test --doctest-modules src

for running the `doctest`.

Linting
~~~~~~~

Lint *galactic-helper-core* using the bash commands:

.. code-block:: shell-session

    $ hatch fmt --check

for running static linting.

.. code-block:: shell-session

    $ hatch fmt

for automatic fixing of static linting issues.

.. code-block:: shell-session

    $ hatch run lint:check

for running dynamic linting.

Documentation
~~~~~~~~~~~~~

Build the documentation using the bash command:

.. code-block:: shell-session

    $ hatch run docs:build

Getting Help
~~~~~~~~~~~~

.. important::

    If you have any difficulties with *galactic-helper-core*, please feel welcome to
    `file an issue`_ on GitLab so that we can help.

.. _file an issue: https://gitlab.univ-lr.fr/galactic/public/src/helpers/galactic-helper-core/-/issues
.. _python 3.11: http://www.python.org
.. _on Windows: https://www.python.org/downloads/windows
.. _hatch: https://hatch.pypa.io/
