This project includes an "Invokefile" to approximate the convenience of npm
scripts, at least until such scripts make their way into
By Invokefile, I'm talking about a
tasks.py script for the Invoke tool.
Using Invoke for common tasks like running tests, formatting code, or
building the documentation relieves us from having to memorize and recite the
command lines or from keeping around a bunch of small shell scripts.
Invoke tasks give us short, easily-remembered names for these functions.
Previously, this project used a Makefile for scripts. Make has the advantage that it is included by default on most Linuxes and OSX, and that it is more well known than Invoke, but I switched to Invoke because it is cross-platform, just like Python. The :doc:`continuous integration <continuous_integration>` scripts use Invoke to run the tests to ensure that (1) the tests are run the same way on every platform and that (2) the Invokefile is written correctly.
The default Invokefile has a few tasks:
|lint||Run the :ref:`linters <code_quality>`: style checkers, type checker, and static analyzers.|
|test||Run the tests (including doctests) with coverage.|
|html||Build the documentation in HTML.|
|serve||Launch a server for the HTML documentation that, whenever a change is detected, rebuilds it and refreshes your browser.|
The scripts assume they are running in the virtual environment of the project. You should invoke them like this:
$ poetry run invoke <task>
Alternatively, if you want every command to conveniently execute in the virtual environment, then you can start a shell in that environment:
$ poetry shell