Installation

There are multiple ways to obtain the pybsm package. The simplest is to install via the pip command. Alternatively, you can install via conda-forge command. For local development, you can use Poetry.

pybsm installation has been tested on Unix and Linux systems.

From pip

pip install pybsm

From conda-forge

conda install -c conda-forge pybsm

From Source

The following assumes Poetry (installation and usage) is already installed.

Note

pybsm currently requires poetry<2.0

Poetry is used for development of pybsm. Unlike the previous options, Poetry will not only allows developers to install any extras they need, but also install developmental dependencies like pytest and pybsm’s linting tools.

Please heed the following warning from Poetry’s own documentation:

Warning

Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system. It should in no case be installed in the environment of the project that is to be managed by Poetry. This ensures that Poetry’s own dependencies will not be accidentally upgraded or uninstalled. In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.

If unfamiliar with Poetry, please take a moment to familiarize yourself using the above links, to ensure the smoothest introduction possible.

Note

Poetry installation is only recommended for advanced pybsm users. For most users, pip or conda installation is sufficient.

Quick Start

cd /where/things/should/go/
git clone https://github.com/kitware/pybsm.git ./
poetry install

Installing Developer Dependencies

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

poetry install --sync --with linting,tests,docs

Building the Documentation

The documentation for pybsm is maintained as a collection of reStructuredText documents in the docs/ folder of the project. The Sphinx documentation tool can process this documentation into a variety of 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, calling the command below will generate HTML format documentation rooted at docs/_build/html/index.html.

poetry run make 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 markup format such as reStructuredText, it is very helpful 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:

poetry run python sphinx_server.py

This will run a small process that watches the docs/ folder contents, as well as the source files in src/pybsm/, 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 an up-to-date preview of the rendered documentation.