Installation Guide

This document explains how to install Haggis.

Installing the Package

PyPI

Haggis is available via pypi, so the recommended way to install it is

pip install haggis

This performs a bare-bones install that depends only on the numpy library. Some of the modules in the libary will not be active without extras. To install all available extras, do

pip install haggis[all]

Extras

To avoid unnecessary heavy dependencies, some of the features of Haggis are only enabled if extras are installed. To install an extra, specify the name, or a comma-separated list of names, in square brackets, e.g.:

pip install haggis[plot,scio]

The following extras are supported:

Extra Dependencies Affected Modules
all All shown below All shown below
docx python-docx >= 0.8.5 haggis.files.docx
latex LaTeX dvips ImageMagick haggis.latex_util
pdf Poppler ImageMagick haggis.files.pdf
ps GhostScript haggis.files.ps
plot matplotlib >= 1.5 haggis.mpl_util haggis.latex_util
scio astropy >= 3.0 scipy >= 0.16 haggis.files.fits
term colorama >= 0.3 [Windows only]  
xlsx openpyxl >= 2.4.8 haggis.files.xlsx

Python dependencies are installed automatically by pip when the corresponding extra is selected. External dependencies are not.

Source

Haggis uses setuptools, so you can install it from source as well. If you have a copy of the source distribution, run

python setup.py install

from the project root directory, with the appropriate privileges. A source distribution can be found on PyPI as well as directly on GitLab.

You can do the same thing with pip if you prefer. Any of the following should work, depending on how you obtained your distribution

pip install git+<URL>/haggis.git@master[all]  # For a remote git repository
pip install haggis.zip[all]                   # For an archived file
pip install haggis[all]                       # For an unpacked folder or repo

Using setup.py or pip should take care of all the Python dependencies.

Tests

Haggis does not currently have any formal unit tests worth mentioning. Eventually, pytest-compatible tests will be added in the tests package.

Documentation

This documentation is built with sphinx (version >= 1.7.1 required).

The API documentation requires the napoleon extension, which is now bundled with sphinx itself. The default viewing experience for the documentation is provided by the ReadTheDocs Theme, which is, however, optional. A version >= 0.4.0 is recommended, but not required.

The documentation can be built from the complete source distribution by using the specially defined command:

python setup.py build_sphinx

Alternatively (perhaps preferably), it can be built using the provided Makefile:

cd doc
make html

Both options work on Windows and Unix-like systems that have make installed. The Windows version does not require make. On Linux you can also do

make -C doc html

The documentation can be found directly on GitLab, or in the source distribution on PyPI. It is not avialable in binary distributions. Any optional Python dependencies that are missing will affect how the documentation is built. Module attributes that are disabled on the local system will not be documented.