.. makefile-rules:

==============
Makefile rules
==============

The repo has a ``Makefile`` to help with development. None of the rules depend
on a virtualenv being activated, but may depend on having python 3 in the path.

Always run ``make`` from the root of the repository.

Rules that delete files
=======================

clean
-----

Deletes files generated by python.

cacheclean
----------

Deletes auto-generated files that aren't covered by any other rule. Good place
for adding new files to delete.

distclean
---------

Deletes files generated on package build, including the packages. Useful
*before* making a new release.

docclean
--------

Deletes the files generated on running the ``Makefile`` in ``docs/``.

coverageclean
-------------

Deletes files created by ``coverage``, which happens if running tests with ``tox``.

testclean
---------

Runs ``coverageclean``, ``clean``, *and* deletes ``.tox``. Useful when there is
*something wrong* when running tests and you need a brutal way to get rid of
extraneous files. ``tox`` will have to spend time on re-building its
virtualenvs afterwards.

nuke
----

Runs all the cleaning jobs. This + ``git stash -u`` should reset the repository
to a pristine state. If something's wrong, don't call Ghostbusters, ``make
nuke`` instead.

Rules that generate files
=========================

tailwind-config
---------------

Runs the ``tailwind_config`` management command, which generates the tailwind
configuration files (``styles.css``, ``tailwind.css``, and custom theme files in
``custom-themes/``) in ``src/argus/htmx/tailwindtheme``. Run this whenever
:setting:`DAISYUI_THEMES` or theme CSS files change.

tailwind
--------

Assumes that the standalone tailwind CLI client is downloaded and uses the
tailwind configuration in ``src/argus/htmx/tailwindtheme`` to generate
a stylesheet that is put in ``src/argus/htmx/static/styles.css``.

When changing themes or the :setting:`DAISYUI_THEMES` setting, run::

    $ make tailwind-config tailwind

upgrade-tailwind
----------------

Uses the confguration in ``src/argus/htmx/tailwindtheme/config.py`` to download
a standalone version of the tailwind compiler (the one used by the ``tailwind``
rule) and the tailwind- and Daisy UI files to be used by that compiler.

This ensures that everybody is using the same version of tailwind and prevents
generating unnecessary versions of ``src/argus/htmx/static/styles.css`` just
because there are different patch revisions of tailwind used by different
developers.

The version in the config is for one of the releases at
`dobicinaitis' tailwind-cli-extra <https://github.com/dobicinaitis/tailwind-cli-extra/releases/>`_

After a change in version, running ``upgrade-tailwind`` should be followed by
running::

    $ make tailwind-config tailwind

setup-tailwind
--------------

Runs ``upgrade-tailwind``, ``tailwind-config``, and ``tailwind`` in sequence.
Use this on a fresh clone or in CI to bootstrap everything from scratch::

    $ make setup-tailwind