tox.ini

[tox]
# https://tox.readthedocs.io/en/latest/config.html
isolated_build = True
envlist = clean,lint,py312,py311,py310,py39,py38,docs,report

# https://github.com/ymyzk/tox-gh-actions breaks with "InterpreterNotFound" when there is a "requires" key
#   clean: commands succeeded
#    lint: commands succeeded
#  ERROR:  py310: InterpreterNotFound: python3.10
#    py39: commands succeeded
#    py38: commands succeeded
requires =
    # Installing with "requires" even though it's not the recommended option
    # https://github.com/enpaul/tox-poetry-installer/#installing
    tox-poetry-installer[poetry] >= 0.9.0

[testenv]
description = Run tests with pytest and coverage
extras = test
depends =
    {py312,py311,py310,py39,py38}: clean
    report: py312,py311,py310,py39,py38
setenv =
    PY_IGNORE_IMPORTMISMATCH = 1
commands =
    python -m pip --version
    python -m pip install -U pip
    # Useful to debug on GitHub Actions
    python -m pip install -U icecream
    # https://pytest-cov.readthedocs.io/en/latest/config.html#caveats
    # https://docs.pytest.org/en/stable/skipping.html
    # show extra test summary info for all tests except passed (failed/error/skipped/xfail/xpassed):
    python -m pytest --cov-config=tox.ini --cov --cov-append --cov-report=term-missing --doctest-modules -s -ra {posargs:}

[testenv:clean]
description = Erase data for the coverage report before running tests
platform = linux
skip_install = true
deps = coverage
commands = coverage erase

[testenv:lint]
description = Lint all files with pre-commit
basepython = python3.9
platform = linux
# pylint needs both these extras:
extras =
    # Install pylint itself
    lint
    # For pylint to inspect tests
    test
deps =
    pip>=21.1
# Run nitpick and pylint with tox, because local repos don't seem to work well with https://pre-commit.ci/
commands =
    # Run Nitpick locally on itself
    nitpick fix
    pylint src/

[testenv:report]
description = Coverage report
platform = linux
skip_install = true
deps = coverage
commands =
    coverage report
    coverage html

[testenv:docs]
description = Build the HTML docs using Sphinx (sphinx-build, API docs, link checks)
basepython = python3.9
platform = linux
extras = doc
# https://tox.readthedocs.io/en/latest/config.html#conf-allowlist_externals
allowlist_externals =
    git
    printf
passenv = GITHUB_ACTIONS GITHUB_REF_NAME
commands =
    # TODO: fix: this step is optional because it generates a different output on GitHub Actions (Ubuntu)
    - python3 docs/autofix_docs.py
    sphinx-apidoc --force --follow-links --module-first --separate --implicit-namespaces --ext-autodoc --ext-doctest --ext-intersphinx --ext-todo --ext-coverage --ext-imgmath --ext-mathjax --ext-ifconfig --ext-viewcode --ext-githubpages --output-dir docs/source src/nitpick/

    # Use these options to debug Sphinx: -nWT --keep-going -vvv
    sphinx-build --color -j auto -d "{toxworkdir}/docs_doctree" -b html docs "{toxworkdir}/docs_out" {posargs}

    # If files were created/changed by the commands above, the git repo will be dirty and the next commands will fail.
    git add .
    git status
    printf "\n\033[1;31mIf tox failed at this point, it means that files were created (see above) and documentation is missing.\n\033[1;31mRun \033[32minvoke doc\033[1;31m in your development machine and commit the generated .rst files.\033[0m\n"
    # TODO: fix: this step is optional because it generates a different output on GitHub Actions (Ubuntu)
    - git diff-index --quiet HEAD --

    # Run link checks after building the docs
    # To stop failing when a page is unreachable, add a hyphen at the start of the line:
    # https://tox.readthedocs.io/en/latest/example/basic.html#ignoring-exit-code
    # Some errors during link check have to be ignored.
    # E.g.: when a new TOML style is added, its link will be broken until a new release is published.
    - sphinx-build --color -j auto -b linkcheck docs "{toxworkdir}/docs_out"

[pytest]
# https://docs.pytest.org/en/stable/customize.html#tox-ini
addopts =
    # Disable HTTP requests on tests (any network calls, actually)
    # https://github.com/miketheman/pytest-socket#usage
    --disable-socket
norecursedirs = .* build dist CVS _darcs {arch} *.egg venv var docs
# https://docs.pytest.org/en/stable/reference.html#confval-testpaths
testpaths = src tests
markers =
    tool_nitpick: options to add to the [tool.nitpick] section on remote styles (see project_remote)

[coverage:run]
# https://coverage.readthedocs.io/en/latest/config.html#run
branch = true
parallel = true
source = src/
omit =
    tests/*
    .tox/*
    */pypoetry/virtualenvs/*
# This config is needed by https://github.com/marketplace/actions/coveralls-python#usage
relative_files = True

[coverage:report]
# https://coverage.readthedocs.io/en/latest/config.html#report
show_missing = true
precision = 2
skip_covered = true
skip_empty = true
sort = Cover

# https://coverage.readthedocs.io/en/latest/excluding.html#advanced-exclusion
exclude_lines =
    # keep-sorted start case=no
    def __repr__
    if 0:
    if __name__ == .__main__.:
    if self.debug:
    if settings.DEBUG
    if TYPE_CHECKING:
    pragma: no cover
    raise AssertionError
    raise NotImplementedError
    # keep-sorted end