From dd35ed25c255739bdb6d4c70082c2462ccedd338 2022-02-04 08:27:58 From: Ben Sturmfels Date: 2022-02-04 08:27:58 Subject: [PATCH] doc: Document installation into a virtualenv. --- diff --git a/README.rst b/README.rst index e103d6f21b33f5f6ddca6979c5106803f1d58819..88b36a28161b4d8a1d1813de6256ae489b7d1cce 100644 --- a/README.rst +++ b/README.rst @@ -17,7 +17,7 @@ Installation python3 -m pip install --user --upgrade . -Of course, if you're familiar with Python development tools, you're welcome to install the module in a virtualenv, somewhere else, etc. +For development, a Python virtual environment may be more appropriate. See the development documentation for details. Development ----------- diff --git a/doc/Development.rst b/doc/Development.rst index b644c63c45794a19be8c4f188dac373e7eb8533c..4b72eb3a174b972ec4b23eb53180e391216b91fd 100644 --- a/doc/Development.rst +++ b/doc/Development.rst @@ -11,6 +11,17 @@ The project comes with a Tox configuration that defines all the tests we expect The next sections describe how to run them standalone in your own development environment, for faster iteration or simpler isolation of problems. +Installing +~~~~~~~~~~ + +Create a virtual environment, for example:: + + python3 -m venv ~/.virtualenvs/conservancy-beancount + +Install the ``conservancy_beancount`` as an editable package including the test dependencies:: + + ~/.virtualenvs/conservancy-beancount/bin/python -m pip install --editable ~/conservancy/conservancy_beancount[test] + Running unit tests ~~~~~~~~~~~~~~~~~~ @@ -18,11 +29,17 @@ Run:: pytest +Alternatively, you can run ``tox`` which will run the tests in a clean virtual +environment with all the relevant dependencies. + Type checking ~~~~~~~~~~~~~ Most of the code is typed, except for very dynamic loader methods. To run the type checker:: + # Beancount includes type declarations but not the `py.typed` flag file mypy + # is looking for to know that. Create it ourselves. + python -c 'import beancount, pathlib; pathlib.Path(beancount.__file__).with_name("py.typed").touch()' mypy conservancy_beancount This is expected to pass just like the unit tests. @@ -34,7 +51,7 @@ Books that use this plugin are expected to say:: plugin "conservancy_beancount.plugin" -When Beancount sees this directive after loading all the data, it passes everything it loaded through the ``run`` function in ``conservancy_beancount/plugin/__init__.py`` to be manipulated. Our ``run`` function, it turn, passes the data through hooks defined in other files under ``conservancy_beancount/plugin`` to normalize data and report errors. ``HookRegistry`` in ``__init__.py`` is the bridge between these two. It supports dynamically choosing which hooks are loaded at runtime, although we currently aren't using that. +When Beancount sees this directive after loading all the data, it passes everything it loaded through the ``run`` function in ``conservancy_beancount/plugin/__init__.py`` to be manipulated. Our ``run`` function, in turn, passes the data through hooks defined in other files under ``conservancy_beancount/plugin`` to normalize data and report errors. ``HookRegistry`` in ``__init__.py`` is the bridge between these two. It supports dynamically choosing which hooks are loaded at runtime, although we currently aren't using that. ``conservancy_beancount/plugin/core.py`` has the base classes for these hooks. The rest of the files in the directory contain the specific hooks that are loaded and run. All the ``meta_foo.py`` files have hook(s) to validate ``foo`` metadata. ``txn_date.py`` verifies that transactions are in the right file by fiscal year.