Installation & Tooling
======================

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

galaxy-graph is managed by `git`_, and can be cloned from its `git repository`_.

.. code:: sh

   git clone https://git.linarphy.net/linarphy/galaxy-graph
   cd galaxy-graph

Once in the created directory, you can now start editing the project.

Tooling
-------

Each tool can be automatically installed with `mise`_. If `mise`_ is installed,
run ``mise trust`` to trust the ``mise.toml`` file. Then running
``mise install`` will automatically install tools, that will be available in the
current directory.

.. caution::
   It is good practice to read the file before trusting it ! It’s not big.

`just`_ is the main development tools. It is a replacement of `make`_, allowing
executing a set of task like running test, generating stubs, etc. To list every
commands and read their documentation, run ``just --list``.

Package manager
^^^^^^^^^^^^^^^

This project uses `hatch`_ as a package and environment manager. It also uses
`uv`_ to quickly download all the dependencies.

To run a command with a given python environment, uses:

.. code:: sh

   hatch run {env_name}:{command}

For example:

.. code:: sh

   hatch run dev:nvim src/galaxy_graph/__init__.py

.. note::
  All `just`_ commands needing a given environment will automatically uses
  `hatch`_: There is no need to run ``hatch run test:just test``.

.. tip::
   Environment are stored in ``pyproject.toml``, in the section 
   ``tool.hatch.env``. They can also be listed with ``hatch env show``.

Test
^^^^

Tests use the `unittest`_ module, available by default on Python. Test coverage
is computed with `coverage.py`_. Running ``just test`` will run every tests and
report the test coverage.

Linting and formatting
^^^^^^^^^^^^^^^^^^^^^^

Maintainer of this project use `ruff`_ to lint and format every python code.

Typing
^^^^^^

Maintainer of this project use `ty`_ to check for type hinting. Running
``just check`` will run every test and check linting or typing error.
``just fix`` will run every test, format the code and try to automatically
safely fix every linting/typing error.

Stubs
^^^^^

Stubs are automatically generated with `mypy`_ and its ``stubgen`` tool. Running
``just stubs`` will generate these stubs.

.. warning::
   Automatically generated stubs have to be corrected each time because mypy
   have a hard time dealing with a module named ``setup`` (and there is a
   submodule ``connection.setup`` in this package). It consists of replacing
   the relative path ``.setup`` to ``galaxy_graph.connection.setup`` in
   ``typings/galaxy_graph/connection/__init__.pyi`` and
   ``typings/galaxy_graph/connection/state.pyi``.

.. _git: https://git-scm.com
.. _git repository: https://git.linarphy.net/linarphy/galaxy-graph
.. _mise: https://mise.jdx.dev
.. _just: https://just.systems
.. _make: https://www.gnu.org/software/make
.. _hatch: https://hatch.pypa.io
.. _uv: https://docs.astral.sh/uv
.. _unittest: https://docs.python.org/3/library/unittest.html
.. _coverage.py: https://coverage.readthedocs.io
.. _ruff: https://docs.astral.sh/ruff
.. _ty: https://docs.astral.sh/ty
.. _mypy: https://mypy.readthedocs.io