sphinx-icontract 1.1.0

Extend sphinx to include icontracts.

sphinx-icontract

Sphinx-icontract extends Sphinx to include icontracts of classes and functions in the documentation.

Usage

Sphinx-icontract is based on the sphinx.ext.autodoc module. You need to specify both modules in extensions of your Sphinx configuration file (conf.py).

Here is an example excerpt:

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_icontract'
]

Installation

• Install sphinx-icontract with pip:

pip3 install sphinx-icontract

Development

• Check out the repository.

• In the repository root, create the virtual environment:

python3 -m venv venv3

• Activate the virtual environment:

source venv3/bin/activate

• Install the development dependencies:

pip3 install -e .[dev]

We use tox for testing and packaging the distribution:

tox

Pre-commit Checks

We provide a set of pre-commit checks that lint and check code for formatting.

Namely, we use:

• yapf to check the formatting.

• The style of the docstrings is checked with pydocstyle.

• Static type analysis is performed with mypy.

• Various linter checks are done with pylint.

• Contracts are linted with pyicontract-lint.

• Doctests are executed using the Python doctest module.

Run the pre-commit checks locally from an activated virtual environment with development dependencies:

./precommit.py

• The pre-commit script can also automatically format the code:

./precommit.py  --overwrite

Versioning

We follow Semantic Versioning. The version X.Y.Z indicates:

• X is the major version (backward-incompatible),

• Y is the minor version (backward-compatible), and

• Z is the patch version (backward-compatible bug fix).