tox.ini

;
; Coverage is always reported at the end of test run.
; There is a dedicated hidden environment for publishing the coverage report
; to the codecov.io service.
;
[tox]
minversion=3.20.1
requires=
    virtualenv>=20.0.35
envlist =
    test,pyflakes,mypy


[testenv]
allowlist_externals =
    git
    rm
    sh
    touch
passenv = *


deps =
    test,test-{py36,py37,py38,pypy3},twisted-apidoc: git+https://github.com/twisted/twisted.git

    test: coverage
    test: pytest
    test: docutils
    test: hypothesis
    test: cython-test-exception-raiser==1.0.0
    test: bs4

    codecov: codecov


commands =
    test: coverage erase
    test: coverage run -m pytest {posargs:pydoctor}
    test: coverage report -m

    ; Publish coverage data on codecov.io
    codecov: coverage xml -o coverage.xml -i
    codecov: codecov

    ; Run current version against twisted trunk
    twisted-apidoc: rm -rf {toxworkdir}/twisted-trunk
    twisted-apidoc: git clone --depth 1 --branch trunk https://github.com/twisted/twisted.git {toxworkdir}/twisted-trunk
    twisted-apidoc: /bin/sh -c "{toxworkdir}/twisted-trunk/bin/admin/build-apidocs {toxworkdir}/twisted-trunk/src {toxworkdir}/twisted-apidocs-build > {toxworkdir}/twisted-apidocs.log"
    twisted-apidoc: /bin/cat {toxworkdir}/twisted-apidocs.log


[testenv:pyflakes]
description = Run pyflakes over the pydoctor code

deps: pyflakes

commands =
    ; Custom pyflakes run to exlcude test files.
    /bin/sh -c "find pydoctor/ -name \*.py ! -path '*/testpackages/*' | xargs pyflakes"
    pyflakes docs


[testenv:cpython-apidocs]
description = Build CPython API documentation

extras = rst

commands =
    sh -c "if [ ! -d {toxworkdir}/cpython ]; then \
        git clone --depth 1 https://github.com/python/cpython.git {toxworkdir}/cpython; \
        fi"
    sh -c "cd {toxworkdir}/cpython && git pull"
    touch {toxworkdir}/cpython/Lib/__init__.py
    rm -rf {toxworkdir}/cpython-output
    pydoctor \
        --docformat=restructuredtext \
        --project-base-dir={toxworkdir}/cpython \
        --html-output={toxworkdir}/cpython-output \
        {toxworkdir}/cpython/Lib


[testenv:cpython-summary]
description = Parse CPython code and write a summary only

extras = rst

commands =
    sh -c "if [ ! -d {toxworkdir}/cpython ]; then \
        git clone --depth 1 https://github.com/python/cpython.git {toxworkdir}/cpython; \
        fi"
    sh -c "cd {toxworkdir}/cpython && git pull"
    touch {toxworkdir}/cpython/Lib/__init__.py
    rm -rf {toxworkdir}/cpython-summary-output
    # TODO: Switch to restructuredtext when #261 is fixed.
    pydoctor \
        --docformat=plaintext \
        --project-base-dir={toxworkdir}/cpython \
        --html-output={toxworkdir}/cpython-summary-output \
        --html-summary-pages \
        {toxworkdir}/cpython/Lib


[testenv:mypy]
description = run mypy (static type checker)

deps =
    mypy>=0.770
    mypy-zope
    typing-extensions
    ; Libraries which include type annotations:
    hypothesis
    pytest>=6.0.0
    sphinx>=3.4.0
    git+https://github.com/twisted/twisted.git

commands =
    mypy                                       \
        --cache-dir="{toxworkdir}/mypy_cache"  \
        {tty:--pretty:}                        \
        {posargs:pydoctor docs/epytext_demo}


[testenv:apidocs]
description = Build only the API documentation

commands =
    pydoctor \
    --project-name=pydoctor \
    --project-url=https://github.com/twisted/pydoctor/ \
    --html-viewsource-base=https://github.com/twisted/pydoctor/tree/master \
    --html-output=build/apidocs \
    --project-base-dir="{toxinidir}" \
    --docformat=epytext \
    --intersphinx=https://docs.python.org/3/objects.inv \
    --intersphinx=https://twistedmatrix.com/documents/current/api/objects.inv \
    --intersphinx=https://urllib3.readthedocs.io/en/latest/objects.inv \
    --intersphinx=https://requests.readthedocs.io/en/latest/objects.inv \
    --intersphinx=https://www.attrs.org/en/stable/objects.inv \
    --make-html --warnings-as-errors \
    pydoctor


[testenv:docs]
description = Build the full documentation

extras = docs

commands =
    sphinx-build -aE -b html {toxinidir}/docs/source {toxinidir}/build/docs
    sphinx-build -aE -b spelling {toxinidir}/docs/source {toxinidir}/build/docs


[testenv:testdocs]
description = Build and test the full documentation

extras = docs
deps = pytest

setenv =
    TOX_INI_DIR = {toxinidir}

allowlist_externals = echo

commands =
    echo "::group::Sphinx build"
    sphinx-build -aE -b html -W {toxinidir}/docs/source {toxinidir}/build/docs
    echo "::endgroup::"

    echo "::group::Main inventory dump"
    python -m sphinx.ext.intersphinx {toxinidir}/build/docs/api/objects.inv
    echo "::endgroup::"

    echo "::group::Epytext demo inventory dump"
    python -m sphinx.ext.intersphinx {toxinidir}/build/docs/docformat/epytext/demo/objects.inv
    echo "::endgroup::"

    pytest -v docs/test.py