tox.ini

[tox]
envlist = py36,py37,py38,py39,py310,py311,py312
isolated_build = true
minversion = 3.21.0

[testenv]
deps =
    .[testing,tunnel,metrics]
# NOTE: The command is invoked by the script name and not via
# NOTE: `{envpython} -m pytest` because it'd add CWD into $PYTHONPATH
# NOTE: testing the project from the Git checkout
# NOTE: rather than one installed.
commands = pytest {posargs:}


[dists]
setenv =
  PEP517_OUT_DIR = {env:PEP517_OUT_DIR:{toxinidir}{/}dist}


[testenv:build-docs]
allowlist_externals =
  git
basepython = python3
commands_pre =
  {envpython} -m pip install \
    {toxinidir}[tunnel,metrics]
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" \
    . \
    "{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
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
isolated_build = true
passenv =
  SSH_AUTH_SOCK
skip_install = false
usedevelop = false


[testenv:doctest-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
commands_pre = {[testenv:build-docs]commands_pre}
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Spellcheck docs site:
  python -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b doctest --color \
    -d "{toxworkdir}/docs_doctree" \
    . "{toxworkdir}/docs_out"
changedir = {[testenv:build-docs]changedir}
deps = {[testenv:build-docs]deps}
description = Doctest The Docs
isolated_build = {[testenv:build-docs]isolated_build}
passenv = {[testenv:build-docs]passenv}
skip_install = {[testenv:build-docs]skip_install}
usedevelop = {[testenv:build-docs]usedevelop}


[testenv:linkcheck-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
commands_pre = {[testenv:build-docs]commands_pre}
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Spellcheck docs site:
  python -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b linkcheck --color \
    -d "{toxworkdir}/docs_doctree" \
    . "{toxworkdir}/docs_out"
changedir = {[testenv:build-docs]changedir}
deps = {[testenv:build-docs]deps}
description = Linkcheck The Docs
isolated_build = {[testenv:build-docs]isolated_build}
passenv = {[testenv:build-docs]passenv}
skip_install = {[testenv:build-docs]skip_install}
usedevelop = {[testenv:build-docs]usedevelop}


[testenv:spellcheck-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
commands_pre = {[testenv:build-docs]commands_pre}
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Spellcheck docs site:
  python -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b spelling --color \
    -d "{toxworkdir}/docs_doctree" \
    . "{toxworkdir}/docs_out"
changedir = {[testenv:build-docs]changedir}
deps =
  sphinxcontrib-spelling == 7.7.0
  -r{toxinidir}/docs/requirements.in
description = Spellcheck The Docs
isolated_build = {[testenv:build-docs]isolated_build}
passenv = {[testenv:build-docs]passenv}
skip_install = {[testenv:build-docs]skip_install}
usedevelop = {[testenv:build-docs]usedevelop}


[testenv:make-changelog]
basepython = python3
depends =
  check-changelog
description =
  Generate a changelog from fragments using Towncrier. Getting an
  unreleased changelog preview does not require extra arguments.
  When invoking to update the changelog, pass the desired version as an
  argument after `--`. For example, `tox -e {envname} -- 1.3.2`.
commands =
  {envpython} -m \
    towncrier.build \
    --version \
    {posargs:'[UNRELEASED DRAFT]' --draft}
deps =
  towncrier == 21.3.0
isolated_build = true
skip_install = true


[testenv:check-changelog]
basepython = {[testenv:make-changelog]basepython}
description =
  Check Towncrier change notes
commands =
  {envpython} -m \
    towncrier.check \
    --compare-with origin/main \
    {posargs:}
deps =
  {[testenv:make-changelog]deps}
isolated_build = {[testenv:make-changelog]isolated_build}
skip_install = {[testenv:make-changelog]skip_install}


[testenv:cleanup-dists]
description =
  Wipe the the `{env:PEP517_OUT_DIR}{/}` folder
usedevelop = false
skip_install = true
deps =
setenv =
  {[dists]setenv}
commands =
  {envpython} -c \
    'import os, shutil, sys; dists_dir = os.getenv("PEP517_OUT_DIR"); shutil.rmtree(dists_dir, ignore_errors=True); sys.exit(os.path.exists(dists_dir))'


[testenv:build-dists]
description =
  Build non-universal dists and put them into
  the `{env:PEP517_OUT_DIR}{/}` folder
depends =
  cleanup-dists
isolated_build = true
# `usedevelop = true` overrides `skip_install` instruction, it's unwanted
usedevelop = false
skip_install = true
deps =
  build >= 0.7.0, < 0.8.0
passenv =
  PEP517_BUILD_ARGS
setenv =
  {[dists]setenv}
commands =
  {envpython} -m build \
    --outdir '{env:PEP517_OUT_DIR}{/}' \
    {posargs:{env:PEP517_BUILD_ARGS:}} \
    '{toxinidir}'


[testenv:metadata-validation]
description =
  Verify that dists under the `{env:PEP517_OUT_DIR}{/}` dir
  have valid metadata
depends =
  build-dists
deps =
  twine
usedevelop = false
skip_install = true
setenv =
  {[dists]setenv}
commands =
  {envpython} -m twine check \
    --strict \
    {env:PEP517_OUT_DIR}{/}*


[testenv:lint]
description =
  Enforce quality standards under `{basepython}` ({envpython})
commands =
  {envpython} -m \
    pre_commit run \
    --show-diff-on-failure \
    --hook-stage manual \
    {posargs:--all-files -v}

  # 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 =
  pre-commit
  pylint >= 2.5.3
  pylint-pytest < 1.1.0
  -r docs/requirements.in
  -r benchmark/requirements.txt
  .[tunnel,metrics,testing]
isolated_build = true
skip_install = true