Installation
There are two ways to get ahold of SMQTK-Core. The simplest is to install via the pip command. Alternatively, the source tree can be acquired and be locally developed using Poetry.
For more information on the use of Poetry, follow these links fr installation and usage documentation.
From pip
pip install smqtk-core
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/Kitware/smqtk-core.git ./
poetry install
# Since we're from source we can test the installation.
poetry run pytest
# We can also build the local documentation as it may be more up to date then ReadTheDocs.
cd docs
make html
Installing Python dependencies
This project uses Poetry for depedency management, environment consistency,
version management, package building and publishing to PYPI.
Dependencies are abstractly defined in the pyproject.toml
file.
Additionally, specifically pinned versions are specified in the
poetry.lock
file for development environment consistency.
Both of these files can be found in the root of the source tree.
The following command installs both installation and development dependencies
as specified in the pyproject.toml
file, with versions specified
(including for transitive dependencies) in the poetry.lock
file:
poetry install
Building the Documentation
The documentation for SMQTK-Core 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 smqtk_core/
, 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.