Setup Guide¶
This document explains how to obtain, install, and use Puzzle Solvers.
Contents:
Getting the Package¶
PyPI¶
Puzzle Solvers is available on pypi, so the recommended way to install it is
pip install puzzle-solvers
matplotlib is an optional dependency, which can be installed using the
mpl
extra:
pip install puzzle-solvers[mpl]
Source¶
You can obtain a copy of the Puzzle Solvers source code from GitLab at https://gitlab.com/madphysicist/puzzle-solvers. The simplest way to keep up with changes is to clone the repo:
git clone git@gitlab.com:madphysicist/puzzle-solvers.git
Puzzle Solvers uses setuptools, so you can install it from source as well. Once you have a copy of the source distribution, run
python setup.py install
from the project root directory, with the appropriate privileges.
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>/puzzle-solvers.git@master[mpl] # For a remote git repository
pip install puzzle-solvers.zip[mpl] # For an archived file
pip install puzzle-solvers[mpl] # For an unpacked folder or repo
Usage¶
Puzzle Solvers is intended primarily as a library. Once it is properly installed, it can be imported as any normal python library:
import puzzle_solvers
The individual modules provide tools for specific puzzle types.
Demos¶
Each module in puzzle_solvers
comes with a corresponding demo in
puzzle_solvers.demos
. Each demo is a standalone script that is
intended to be run as a packaged module. For example:
python -m puzzle_solvers.demos.elimination
Tests¶
Puzzle Solvers does not currently have any formal unit tests available.
However, running through all of the demos and tutorials serves as a
non-automated set of tests, since they exercise nearly every aspect of the
solvers. Eventually, pytest-compatible tests will be added in the
tests
package.
Documentation¶
Online¶
The documentation is available online at https://puzzle-solvers/readthedocs.io.
Building¶
If you intend to build the documentation, you must have Sphinx installed, and optionally the ReadTheDocs Theme extension for optimal viewing.
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/Batch script:
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 is not present in the PyPI source distributions, only directly from GitLab.