tox.ini

[tox]
envlist =
    # NOTE: keep this in sync with the env list in .github/workflows/ci.yml.
    py{38,39,310,311,312,py3}-pip{previous,latest,main}-coverage
    pip{previous,latest,main}-coverage
    pip{previous,latest,main}
    checkqa
    readme
skip_missing_interpreters = True

[testenv]
description = run the tests with pytest
extras =
    testing
    coverage: coverage
deps =
    pipprevious: pip==22.2.*
    piplatest: pip
    pipmain: https://github.com/pypa/pip/archive/main.zip
setenv =
    coverage: PYTEST_ADDOPTS=--strict-markers --doctest-modules --cov --cov-report=term-missing --cov-report=xml {env:PYTEST_ADDOPTS:}
commands_pre =
    piplatest: python -m pip install -U pip
    pip --version
commands = pytest {posargs}
passenv =
    CI
    FORCE_COLOR
    GITHUB_ACTIONS
    MYPY_FORCE_COLOR
    PRE_COMMIT_COLOR
    PY_COLORS
pip_pre=True

[testenv:checkqa]
description = format the code base and check its quality
skip_install = True
deps = pre-commit
commands_pre =
commands = pre-commit run --all-files --show-diff-on-failure

[testenv:readme]
description = check whether the long description will render correctly on PyPI
deps =
    build
    twine
commands_pre =
commands =
    python -m build --outdir {envtmpdir} --sdist {toxinidir}
    twine check --strict {envtmpdir}{/}*
skip_install = true

[testenv:pip-compile-docs]
description = compile requirements for the documentation
commands_pre =
commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs}

[testenv:build-docs]
description = build the documentation
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
commands_pre =
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
isolated_build = true
passenv =
  SSH_AUTH_SOCK
skip_install = false
allowlist_externals =
  git


[testenv:preview-docs]
description = preview the docs
deps =
  sphinx-autobuild
  {[testenv:build-docs]deps}
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build the html docs with sphinx-autobuild:
  {envpython} -m sphinx_autobuild \
    -j auto \
    -b html \
    -n \
    -W \
    -d "{temp_dir}/.doctrees" \
    . \
    --watch ../README.md \
    --watch ../CHANGELOG.md \
    "{envdir}/docs_out"

changedir = {[testenv:build-docs]changedir}
isolated_build = {[testenv:build-docs]isolated_build}
passenv = {[testenv:build-docs]passenv}
skip_install = {[testenv:build-docs]skip_install}
allowlist_externals = {[testenv:build-docs]allowlist_externals}


[testenv:linkcheck-docs]
description = check links in the documentation
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
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build the html docs with Sphinx:
  {envpython} -m sphinx \
    -j auto \
    -b linkcheck \
    {tty:--color} \
    -a \
    -n -W --keep-going \
    -d "{temp_dir}/.doctrees" \
    . \
    "{envdir}/docs_out"
changedir = {toxinidir}/docs
isolated_build = true
passenv =
  SSH_AUTH_SOCK
skip_install = false
allowlist_externals =
  git