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,testdocs


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

[testenv:test]
description = Run tests and coverage report
extras =
    test
commands = 
    coverage erase
    coverage run -m pytest -vv {posargs: pydoctor}
    coverage report -m

[testenv:test-latest-twisted]
description = Run tests with latest Twisted version
deps = 
    git+https://github.com/twisted/twisted.git
extras =
    test
commands = 
    pytest -vv {posargs: pydoctor}

[testenv:codecov]
description = Publish code coverage
deps =
    codecov
commands = 
    ; Publish coverage data on codecov.io
    coverage xml -o coverage.xml -i
    codecov

[testenv:twisted-apidoc]
deps =
    pytest
commands =
    ; Run current version against twisted trunk
    rm -rf {toxworkdir}/twisted-trunk
    git clone --depth 1 --branch trunk https://github.com/twisted/twisted.git {toxworkdir}/twisted-trunk
    - pydoctor --config {toxworkdir}/twisted-trunk/setup.cfg \
        --html-output {toxworkdir}/twisted-apidocs-build \
        --project-base-dir {toxworkdir}/twisted-trunk/ \
        {toxworkdir}/twisted-trunk/src/twisted/ --theme=classic

    pytest -vv docs/tests/test_twisted_docs.py

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

deps: pyflakes

commands =
    ; Custom pyflakes run to exlcude some files. The demo packages are trigerring some unused imports warnings. But pydoctor uses those imports to resolve links. So we skip pyflakes for the demo sites. But not the test files. 
    sh -c "find pydoctor/ -name \*.py ! -path '*/testpackages/*' ! -path '*/sre_parse36.py' ! -path '*/sre_constants36.py' | xargs pyflakes"
    sh -c "find docs/ -name \*.py ! -path '*demo/*' | xargs pyflakes"


[testenv:cpython-apidocs]
description = Build CPython API documentation
deps = 
    pytest
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 \
        ; the sidebar is making the build time two times longer for the cpython docs, 
        ; so we just skip it.
        --no-sidebar \ 
        {toxworkdir}/cpython/Lib
    pytest -vv docs/tests/test_standard_library_docs.py

[testenv:numpy-apidocs]
description = Build numpy API documentation. For now we don't check for any warnings or other errors. The only purpose of this test is to make sure pydoctor doesn't crash.
deps = 
    pytest
commands =
    sh -c "if [ ! -d {toxworkdir}/numpy ]; then \
        git clone --depth 1 https://github.com/numpy/numpy.git {toxworkdir}/numpy; \
        fi"
    sh -c "cd {toxworkdir}/numpy && git pull"
    rm -rf {toxworkdir}/numpy-output
    python3 -c "from pydoctor.driver import main; \
        code = main(['--html-summary-pages', '--quiet', \
        '--html-output={toxworkdir}/numpy-output', \
        '{toxworkdir}/numpy/numpy']); \
        # Code 2 error means bad docstrings, which is OK for this test.
        assert code==2, 'pydoctor exited with code %s, expected code 2.'%code"

# Requires cmake
[testenv:python-igraph-apidocs]
description = Build python-igraph API documentation
deps = 
    pytest
commands =
    sh -c "if [ ! -d {toxworkdir}/python-igraph ]; then \
        git clone --recurse-submodules https://github.com/igraph/python-igraph.git {toxworkdir}/python-igraph; \
        fi"
    sh -c "cd {toxworkdir}/python-igraph && git pull"
    rm -rf {toxworkdir}/python-igraph-output
    sh -c "cd {toxworkdir}/python-igraph/ && python3 ./setup.py bdist_wheel && python3 -m pip install dist/*.whl"
    sh -c "pydoctor \
        --project-url 'https://igraph.org/python' \
        --docformat=epytext \
        --html-output={toxworkdir}/python-igraph-output \
        --introspect-c-modules --quiet \
        $(python3 -c 'import igraph, os; print(os.path.dirname(igraph.__file__))') || true"
    pytest -vv docs/tests/test_python_igraph_docs.py

[testenv:pytype-apidocs]
description = Build pytype API documentation
; The only purpose of this test is to make sure pydoctor doesn't crash.
commands =
    sh -c "if [ ! -d {toxworkdir}/pytype ]; then \
        git clone https://github.com/google/pytype.git {toxworkdir}/pytype; \
        fi"
    sh -c "cd {toxworkdir}/pytype && git pull"
    rm -rf {toxworkdir}/pytype-output
    sh -c "pydoctor \
        --docformat=plaintext \
        --html-output={toxworkdir}/pytype-output \
        --quiet {toxworkdir}/pytype/pytype"

[testenv:git-buildpackage-apidocs]
description = Build git-buildpackage API documentation
; The only purpose of this test is to make sure pydoctor doesn't crash.
commands =
    sh -c "if [ ! -d {toxworkdir}/git-buildpackage ]; then \
        git clone https://salsa.debian.org/agx/git-buildpackage.git {toxworkdir}/git-buildpackage; \
        fi"
    sh -c "cd {toxworkdir}/git-buildpackage && git pull"
    rm -rf {toxworkdir}git-buildpackage-output
    python3 -c "from pydoctor.driver import main; \
        code = main(['--quiet', \
        '--html-output={toxworkdir}/git-buildpackage-output', \
        '{toxworkdir}/git-buildpackage/gbp', '{toxworkdir}/git-buildpackage/tests']); \
        # Code 2 error means bad docstrings, which is OK for this test.
        assert code in [0,2], 'pydoctor exited with code %s, expected code 0 or 2.'%code"

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

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.902
    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
    types-requests
    # FIXME: https://github.com/twisted/pydoctor/issues/504
    # This is pinned for now as newer versions are breaking our static checks.
    types-docutils==0.17.5
    types-toml

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

[testenv:mypy-docutils-stubs]
description = run mypy with docutils-stubs (does not pass for now)
; See: https://github.com/python/typeshed/issues/1269

deps =
    mypy>=0.902
    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
    types-requests
    docutils-stubs
    types-toml

commands =
    mypy                                       \
        --cache-dir="{toxworkdir}/mypy_cache"  \
        --exclude='pydoctor/test/testpackages' \
        {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 \
    --privacy="HIDDEN:pydoctor.test" \
    --make-html --warnings-as-errors \
    {posargs: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 -vv docs/tests/test.py