Installation

There are two ways to get a hold of XAITK-Saliency. The simplest is to install via the pip command. Alternatively, the source tree can be acquired and be locally developed using Poetry (installation and usage).

From pip

pip install xaitk-saliency

This method will install all of the same functionality as when installing from source. If you have an existing installation and would like to upgrade your version, provide the -U/--upgrade option.

From Source

The following assumes Poetry is already installed.

Quick Start

cd /where/things/should/go/
git clone https://github.com/XAITK/xaitk-saliency.git ./
poetry install
poetry run pytest
cd docs
poetry run make html

Installing Python dependencies

This project uses Poetry for depedency management, environment consistency, package building, version management and publishing to PYPI. Dependencies are abstractly defined in the pyproject.toml file, as well as specifically pinned versions in the poetry.lock file, both of which can be found in the root of the source tree.

The following installs both installation and development dependencies as specified in the pyproject.toml file, with versions specified (including for transitive depedencies) in the poetry.lock file:

poetry install

Building the Documentation

The documentation for XAITK-Saliency is maintained as a collection of reStructuredText documents in the docs/ folder of the project. This documentation can be processed by the Sphinx documentation tool into a variety of documentation formats, the most common of which is HTML.

Within the docs/ directory is a Unix Makefile (for Windows systems, a make.bat file with similar capabilities exists). This Makefile takes care of the work required to run Sphinx to convert the raw documentation to an attractive output format. For example, as shown in the quickstart, calling make html will generate HTML format documentation rooted at docs/_build/html/index.html.

Calling the command make help here will show the other documentation formats that may be available (although be aware that some of them require additional dependencies such as TeX or LaTeX)

Live Preview

While writing documentation in a mark up format such as reStructuredText it is very helpful to be able to preview the formatted version of the text. While it is possible to simply run the make html command periodically, a more seamless workflow of this is available. Within the docs/ directory is a small Python script called sphinx_server.py that can simply be called with:

python sphinx_server.py

This will run a small process that watches the docs/ folder contents, as well as the source files in xaitk_saliency/, for changes. make html is re-run automatically when changes are detected. This will serve the resulting HTML files at http://localhost:5500. Having this URL open in a browser will provide you with a relatively up-to-date preview of the rendered documentation.