tox.ini

[tox]
envlist = python
isolated_build = true
minversion = 3.21.0

[testenv]
description = Run test suite
commands =
  {envpython} \
    -m pytest \
      {tty:--color=yes} \
      {posargs:--cov-report=html:{envtmpdir}{/}htmlcov{/}}
deps =
  covdefaults

  pytest
  pytest-cov
  pytest-xdist

  # Ref: https://github.com/tox-dev/tox/issues/1199
  towncrier
isolated_build = true
package = wheel
wheel_build_env = .pkg
usedevelop = false

[testenv:build-dists]
description =
  Build dists and put them into the dist{/} folder
basepython = python3
isolated_build = true
# NOTE: `package_env = none` is needed so it's possible to use `--installpkg`
# NOTE: with the main `testenv`.
# Ref: https://github.com/tox-dev/tox/issues/2442
package_env = ❌ DUMMY NON-EXISTENT ENV NAME ❌
# `usedevelop = true` overrides `skip_install` instruction, it's unwanted
usedevelop = false
skip_install = true
deps =
  build ~= 1.0.0
commands =
  {envpython} -c \
    "import shutil; \
    shutil.rmtree('{toxinidir}{/}dist{/}', ignore_errors=True)"

  {envpython} -m build \
    --outdir '{toxinidir}{/}dist{/}' \
    {posargs:} \
    '{toxinidir}'


[testenv:lint]
description =
  Run the quality checks under {basepython}; run as
  `SKIP=check-id1,check-id2 tox r -e pre-commit` to instruct the underlying
  `pre-commit` invocation avoid running said checks; Use
  `tox r -e pre-commit -- check-id1 --all-files` to select checks matching IDs
  aliases{:} `tox r -e pre-commit -- mypy --all-files` will run 3 MyPy
  invocations, but `tox r -e pre-commit -- mypy-py313 --all-files` runs one.
basepython = python3
commands =
  {envpython} \
    -m pre_commit \
      run \
      --color=always \
      --show-diff-on-failure \
      --hook-stage manual \
      {posargs:--all-files}

  # Print out the advice on how to install pre-commit from this env into Git:
  -{envpython} -c \
  'cmd = "{envpython} -m pre_commit install"; \
    scr_width = len(cmd) + 10; \
    sep = "=" * scr_width; \
    cmd_str = "    $ \{cmd\}";' \
    'print(f"\n\{sep\}\nTo install pre-commit hooks into the Git repo, run:\n\n\{cmd_str\}\n\n\{sep\}\n")'
deps =
  {[testenv]deps}
  {[testenv:build-docs]deps}
  pre-commit >= 2.6.0
  pylint ~= 2.15.0
isolated_build = true
passenv =
  SKIP


[testenv:build-docs]
allowlist_externals =
  git
basepython = python3
depends =
  make-changelog
deps =
  # -r{toxinidir}{/}docs{/}requirements.txt
  # FIXME: re-enable the "-r" + "-c" paradigm once the pip bug is fixed.
  # Ref: https://github.com/pypa/pip/issues/9243
  -r{toxinidir}{/}docs{/}requirements.in
  # -c{toxinidir}{/}docs{/}requirements.txt
description = Build The Docs
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build the html docs with Sphinx:
  {envpython} -m sphinx \
    -j auto \
    -b html \
    {tty:--color} \
    -a \
    -n \
    -W --keep-going \
    -d "{temp_dir}{/}.doctrees" \
    {posargs:} \
    . \
    "{envdir}{/}docs_out"

  # Print out the output docs dir and a way to serve html:
  -{envpython} -c\
  'import pathlib;\
  docs_dir = pathlib.Path(r"{envdir}") / "docs_out";\
  index_file = docs_dir / "index.html";\
  print("\n" + "=" * 120 +\
  f"\n\nDocumentation available under:\n\n\
  \tfile://\{index_file\}\n\nTo serve docs, use\n\n\
  \t$ python3 -m http.server --directory \
  \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
  "=" * 120)'
changedir = {toxinidir}{/}docs
isolated_build = true
passenv =
  SSH_AUTH_SOCK
skip_install = false
# whitelist_externals is a compatibility alias for allowlist_externals @ old tox
whitelist_externals =
  git