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 |
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.