This project uses Pipenv, which can be installed through Homebrew for Mac users. It must be installed before the Makefile targets, or the other commands listed in this document will work.
In order to run a command which relies on the project virtual
environment, such as
python foo.py, it is necessary to
pipenv shell first, which will put you into a
shell that has the correct Python installed, or prefix the
pipenv run (e.g.
pipenv run python foo.py).
# Get to work (from within project directory) # This drops you into a shell inside the project virtual # environment which means that commands that "pipenv run" # may be elided from other commands. pipenv shell
A Makefile is available, run
make help in the
project root to see the available targets.
The Makefile has targets for managing dependencies, but it may be easier, particularly for Python developers, to simply invoke Pipenv directly. Example commands are listed below.
If you prefer not to use the Makefile, or if you need to add or remove dependencies, the following commands will allow you to manage dependencies.
# Fetch runtime dependencies pipenv sync # Fetch runtime and development dependencies pipenv sync --dev # Add a runtime dependency pipenv install <package> # Add a development dependency pipenv install --dev <package>
Documentation tests are also fine for simple cases.
# Run tests pipenv run python -m pytest # or make check-fast check-slow # or make check
There is a
Dockerfile in the repo root. The image it
describes is used for running tests in CI and can be used
locally for convenience.
When dependencies change the image must be rebuilt and the
new version pushed to Docker Hub. This can be done with
make container if you have the correct permissions.
Otherwise, ask a maintainer to do it for you.
There is also a file called
Dockerfile_run. This is a
runner image that is available for users who prefer to run
PolyA through Docker (which is often more convenient). The
runner image can be built with
and, assuming sufficient permissions, pushed to Docker Hub with
The scripts assume you are building the latest version of
the image and so set the
latest tag. If this is not the
case, it is fairly simple to issue the correct Docker commands
This image can be found on Docker Hub: https://hub.docker.com/repository/docker/traviswheelerlab/polya
We use Sphinx for project documentation. Run
to update the documentation sources and build the HTML. Use
make docs-serve to serve the documentation locally.
Generating a new release is a four step process. The first step MUST be completed first, but the rest may be done in any order.
First, update the value of
incrementing the various portions of the version number
accordingly. We would like to follow
Semantic Versioning, at least in general.
Commit your changes to the master branch.
a “release” on GitHub. The tag should consist of a “v”, followed
immediately by the version number you chose above. For example:
make build-package, followed by
make publish-package assuming there aren’t any build errors.
Fourth, and finally, create and push a new runner image to Docker
Hub. Build the image by running
and publish it with
./tool/push-runner-image.sh. The version
tag will be set automatically and the
latest tag will also be