Development

Commands for the development of fabsetup.

Setup

Clone this repository an cd into it:

git clone https://github.com/theno/fabsetup.git
cd fabsetup

Fabsetup supports several Python versions, Python 3.5, Python 3.6, Python 3.7, Python 3.8, and Python 3.9. In order to run the following commands and set up an environment with all of this Pythons, an installation of pyenv is required.

Install and set up latest python versions with pyenv:

# learn for the latest pythons
pyenv update

# install them
pys=()  # python versions
for minor in {5..9}; do
  latest=$(pyenv install --list | \
           grep -oP "(?<=^  )3\.$minor\.\d+$" | tail -1)
  pys=("${pys[@]}" $latest)
  pyenv install --skip-existing  $latest
done

# create virtualenv for build tasks
py39=${pys[-1]}
pyenv virtualenv ${py39} fabsetup_py39

# activate pythons
#   vanilla Python-3.5, -3.6, -3.7, -3.8
#   and Python-3.9 virtualenv fabsetup_py39
pyenv local ${pys[@]::${#pys[@]}-1} fabsetup_py39

# install build dependencies (pytest, tox, sphinx)
# in virtualenv fabsetup_py39
pip3.9 install --upgrade -e .[devel]

Show and check environment. On success, the return code of the following commands is 0:

# active pythons
pyenv version |& \
        grep -zE '3\.5.*3\.6.*3\.7.*3\.8.*fabsetup_py39.*python-version'

# virtualenv fabsetup_py39
pyenv which python3.9 |& grep fabsetup_py39

# correct pytest version is active
pyenv which pytest    |& grep fabsetup_py39

# correct tox version is active
tox --version         |& grep fabsetup_py39

# correct pip version is active
pip3.9 --version      |& grep fabsetup_py39

# required packages are installed
pip3.9 freeze         |& grep -zE 'fabsetup.*pytest.*Sphinx.*tox'

Tests

Run pytest. Executes unit tests against Python 3.9:

pytest tests -s

# long-winded way
PYTHONPATH=  python3.9 -m pytest tests/ -s

Run doctest. Executes and tests code examples in docstrings:

pytest fabsetup --doctest-modules

# long-winded way
PYTHONPATH=  python3.9 -m pytest fabsetup/ --doctest-modules

Run tox. Against Python 3.5, Python 3.6, Python 3.7, Python 3.8, and Python 3.9 it executes check-manifest, setup.py check, unit tests, doctests, flake8, and coverage check:

tox

# long-winded way
PYTHONPATH=  python3.9 -m tox

Mutation Tests

Run mutmut which executes mutation tests in order to test the unit tests:

mutmut run

# show results
mutmut results
mutmut show

# show mutation diff
mutmut show MUTATION_ID

# clean-up
rm -f .mutmut-cache

Run fabsetup

Run fabsetup devel command:

fabsetup

# long-winded ways
~/.pyenv/versions/fabsetup_py39/bin/fabsetup
~/.pyenv/versions/fabsetup_py39/bin/python  -m fabsetup
python3.9 -m fabsetup
python3.9  fabsetup/__main__.py

Run with debug output :

INVOKE_DEBUG=1 fabsetup

fabsetup --debug

Documentation

Create Sphinx HTML documentation:

ln -s ../README.md  docs/
cd docs && make clean html; cd ..

Update API docs structure, run command sphinx-apidoc that generates Sphinx sources which includes the docstrings with autodoc:

rm -rf docs/api && sphinx-apidoc -o docs/api --module-first fabsetup

# apply tweaks
sed -i '/Submodules/{ N; s/.*----------//; }' docs/api/fabsetup{,.{fab,}utils}.rst
sed -i 's/fabsetup package/fabsetup API/' docs/api/fabsetup.rst
sed -i 's/Subpackages/Submodules/' docs/api/fabsetup.rst
sed -i 's/ package$//' docs/api/fabsetup.{fab,}utils.rst
sed -i 's/ module$//g' docs/api/fabsetup{,.{fab,}utils}.rst
rm docs/api/modules.rst

cd docs && make clean html; cd ..

This commands are executed to create the readthedocs documentation: https://github.com/theno/fabsetup/blob/main/.readthedocs.yaml