Extend sphinx to include icontracts.
Project description
sphinx-icontract
================
.. image:: https://api.travis-ci.com/Parquery/sphinx-icontract.svg?branch=master
:target: https://api.travis-ci.com/Parquery/sphinx-icontract.svg?branch=master
:alt: Build Status
.. image:: https://coveralls.io/repos/github/Parquery/sphinx-icontract/badge.svg?branch=master
:target: https://coveralls.io/github/Parquery/sphinx-icontract?branch=master
:alt: Coverage
.. image:: https://badge.fury.io/py/sphinx-icontract.svg
:target: https://pypi.org/project/sphinx-icontract/
:alt: PyPi
.. image:: https://img.shields.io/pypi/pyversions/sphinx-icontract.svg
:alt: PyPI - Python Version
Sphinx-icontract extends Sphinx to include icontracts of classes and functions in the documentation.
Usage
=====
Sphinx-icontract is based on the :py:module:`sphinx.ext.autodoc` module. You need to specify both modules in
``extensions`` of your Sphinx configuration file (``conf.py``).
Here is an example excerpt:
.. code-block:: python
# 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:
.. code-block:: bash
pip3 install sphinx-icontract
Development
===========
* Check out the repository.
* In the repository root, create the virtual environment:
.. code-block:: bash
python3 -m venv venv3
* Activate the virtual environment:
.. code-block:: bash
source venv3/bin/activate
* Install the development dependencies:
.. code-block:: bash
pip3 install -e .[dev]
We use tox for testing and packaging the distribution:
.. code-block:: bash
tox
Pre-commit Checks
-----------------
We provide a set of pre-commit checks that lint and check code for formatting.
Namely, we use:
* `yapf <https://github.com/google/yapf>`_ to check the formatting.
* The style of the docstrings is checked with `pydocstyle <https://github.com/PyCQA/pydocstyle>`_.
* Static type analysis is performed with `mypy <http://mypy-lang.org/>`_.
* Various linter checks are done with `pylint <https://www.pylint.org/>`_.
* Contracts are linted with `pyicontract-lint <https://github.com/Parquery/pyicontract-lint>`_.
* Doctests are executed using the Python `doctest module <https://docs.python.org/3.5/library/doctest.html>`_.
Run the pre-commit checks locally from an activated virtual environment with development dependencies:
.. code-block:: bash
./precommit.py
* The pre-commit script can also automatically format the code:
.. code-block:: bash
./precommit.py --overwrite
Versioning
==========
We follow `Semantic Versioning <http://semver.org/spec/v1.0.0.html>`_. 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).
================
.. image:: https://api.travis-ci.com/Parquery/sphinx-icontract.svg?branch=master
:target: https://api.travis-ci.com/Parquery/sphinx-icontract.svg?branch=master
:alt: Build Status
.. image:: https://coveralls.io/repos/github/Parquery/sphinx-icontract/badge.svg?branch=master
:target: https://coveralls.io/github/Parquery/sphinx-icontract?branch=master
:alt: Coverage
.. image:: https://badge.fury.io/py/sphinx-icontract.svg
:target: https://pypi.org/project/sphinx-icontract/
:alt: PyPi
.. image:: https://img.shields.io/pypi/pyversions/sphinx-icontract.svg
:alt: PyPI - Python Version
Sphinx-icontract extends Sphinx to include icontracts of classes and functions in the documentation.
Usage
=====
Sphinx-icontract is based on the :py:module:`sphinx.ext.autodoc` module. You need to specify both modules in
``extensions`` of your Sphinx configuration file (``conf.py``).
Here is an example excerpt:
.. code-block:: python
# 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:
.. code-block:: bash
pip3 install sphinx-icontract
Development
===========
* Check out the repository.
* In the repository root, create the virtual environment:
.. code-block:: bash
python3 -m venv venv3
* Activate the virtual environment:
.. code-block:: bash
source venv3/bin/activate
* Install the development dependencies:
.. code-block:: bash
pip3 install -e .[dev]
We use tox for testing and packaging the distribution:
.. code-block:: bash
tox
Pre-commit Checks
-----------------
We provide a set of pre-commit checks that lint and check code for formatting.
Namely, we use:
* `yapf <https://github.com/google/yapf>`_ to check the formatting.
* The style of the docstrings is checked with `pydocstyle <https://github.com/PyCQA/pydocstyle>`_.
* Static type analysis is performed with `mypy <http://mypy-lang.org/>`_.
* Various linter checks are done with `pylint <https://www.pylint.org/>`_.
* Contracts are linted with `pyicontract-lint <https://github.com/Parquery/pyicontract-lint>`_.
* Doctests are executed using the Python `doctest module <https://docs.python.org/3.5/library/doctest.html>`_.
Run the pre-commit checks locally from an activated virtual environment with development dependencies:
.. code-block:: bash
./precommit.py
* The pre-commit script can also automatically format the code:
.. code-block:: bash
./precommit.py --overwrite
Versioning
==========
We follow `Semantic Versioning <http://semver.org/spec/v1.0.0.html>`_. 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).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sphinx-icontract-1.0.0.tar.gz
(4.3 kB
view hashes)