tox.ini

# spell-checker:ignore toxinidir passenv usedevelop testenv basepython envpython linkcheck changedir envdir envlist minversion toxworkdir posargs envname skipsdist setenv
[tox]
envlist =
  lint
  docs
  test
minversion = 3.21.0
skip_install = true
skipsdist = true

[docs]
# do not use continuation with vars, see https://github.com/tox-dev/tox/issues/2069
sphinx_common_args =
  # https://github.com/sphinx-doc/sphinx/pull/10260
  -j auto --color -a -n -W --keep-going -T -d "{temp_dir}/.doctrees" . "{envdir}/docs_out"

[testenv]
description =
  Run tests
  test-node12: with node 12
  test-node14: with node 14
  test-node16: with node 16
passenv =
  CI
  GITHUB_ACTIONS
  HOME
  SSH_AUTH_SOCK
  TERM
setenv =
  FORCE_COLOR=1
  NODE_VERSION=stable
  node12: NODE_VERSION=12
  node14: NODE_VERSION=14
  node16: NODE_VERSION=16
  PIP_CONSTRAINTS=requirements.txt
allowlist_externals =
  bash
  node
# Activation of node version is not persistent and nvm works only from
# within `bash --login`, do not call nvm/npm/node without it under tox as
# you might end-up using system version, if any
commands_pre =
  {node12,node14,node16}: bash --login -c "nvm install --latest-npm --default {env:NODE_VERSION}"
commands_post =
  # restore nvm default alias to stable version
  {node12,node14,node16}: bash --login -c "nvm alias default stable"
commands =
  bash --login -c "npm run test"

skip_install = true

# keep them, so tox 3 can lists these as additional envs:
[testenv:test-{node12,node14,node16}]
description =
  Run tests
  test-node12: with node 12
  test-node14: with node 14
  test-node16: with node 16

[testenv:deps]
description = Bump all test dependencies
# Using py310 in order to make pip-compile consistent.
basepython = python3.10
deps =
  -c requirements.txt
  pip-tools >= 6.5.1
commands =
  # dependabot supports only 'requirements.txt' filename but we use it as
  # a constraints files
  bash -c "PIP_CONSTRAINTS= pip-compile -q --no-annotate \
    -r requirements.in \
    -o requirements.txt"

[testenv:docs]
allowlist_externals =
  git
changedir = {toxinidir}/docs
commands_pre =
  # Retrieve possibly missing commits:
  - git fetch --unshallow
  - git fetch --tags
commands =
  {envpython} -m sphinx -b html {[docs]sphinx_common_args}
  {envpython} -m sphinx -b linkcheck {[docs]sphinx_common_args}
  {envpython} -m sphinx -b spelling {[docs]sphinx_common_args}

  # 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)'

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
passenv =
  SSH_AUTH_SOCK
skip_install = true
usedevelop = false


[testenv:lint]
description = Run all linters
deps =
  pre-commit >= 2.17.0
commands =
  # Commands are the same as running `npm run lint`:
  pre-commit run -a
skip_install = true


[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`.
envdir = {toxworkdir}/changelog
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}
envdir = {[testenv:make-changelog]envdir}
isolated_build = {[testenv:make-changelog]isolated_build}
skip_install = {[testenv:make-changelog]skip_install}


[testenv:draft-changelog]
basepython = {[testenv:make-changelog]basepython}
description =
  Print out the Towncrier-managed change notes
  draft for the next release to stdout
commands =
  # NOTE: `sh` invocation is required to suppress stderr from
  # NOTE: towncrier since it does not have own CLI flags for
  # NOTE: doing this.
  sh -c "2>/dev/null \
    {envpython} -m \
    towncrier.build \
    --version '[UNRELEASED DRAFT]' \
    --draft"
envdir = {[testenv:make-changelog]envdir}
deps =
  {[testenv:make-changelog]deps}
isolated_build = {[testenv:make-changelog]isolated_build}
skip_install = {[testenv:make-changelog]skip_install}