2

I am trying to build the docs of my project with Sphinx, tox, and GitLab CI. Although it works fine locally I am getting this very unintuitive error without any proper error message on GitLab CI. Any ideas on what might be going on and how to fix it?

Everything is pretty much standard PyScaffold-based.

$ tox -v -e docs
...
docs: commands[0]> sphinx-build -T -v --color -b html -d /builds/repo/dlproject/docs/_build/doctrees /builds/repo/dlproject/docs /builds/repo/dlproject/docs/_build/html
Running Sphinx v7.0.1
loading configurations for dlproject 0.0.post1.dev43+g1bfa027 ...
Creating file /builds/repo/dlproject/docs/api/dlproject.rst.
Creating file /builds/repo/dlproject/docs/api/dlproject.data.rst.
Creating file /builds/repo/dlproject/docs/api/dlproject.design.rst.
Creating file /builds/repo/dlproject/docs/api/dlproject.model.rst.
Creating file /builds/repo/dlproject/docs/api/dlproject.sequence.rst.
Creating file /builds/repo/dlproject/docs/api/modules.rst.
making output directory... done
locale_dir /builds/repo/dlproject/docs/locales/en/LC_MESSAGES does not exists
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
loading intersphinx inventory from https://docs.python.org/3.10/objects.inv...
loading intersphinx inventory from https://matplotlib.org/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://scikit-learn.org/stable/objects.inv...
loading intersphinx inventory from https://pandas.pydata.org/pandas-docs/stable/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/reference/objects.inv...
loading intersphinx inventory from https://setuptools.pypa.io/en/stable/objects.inv...
loading intersphinx inventory from https://pyscaffold.org/en/stable/objects.inv...
intersphinx inventory has moved: https://matplotlib.org/objects.inv -> https://matplotlib.org/stable/objects.inv
intersphinx inventory has moved: https://docs.scipy.org/doc/scipy/reference/objects.inv -> https://docs.scipy.org/doc/scipy/objects.inv
[autosummary] generating autosummary for: api/dlproject.data.rst, api/dlproject.design.rst, api/dlproject.model.rst, api/dlproject.rst, api/dlproject.sequence.rst, api/modules.rst, authors.rst, changelog.rst, contributing.rst, index.rst, license.rst, readme.rst
docs: exit -4 (7.65 seconds) /builds/repo/dlproject> sphinx-build -T -v --color -b html -d /builds/repo/dlproject/docs/_build/doctrees /builds/repo/dlproject/docs /builds/repo/dlproject/docs/_build/html pid=346
.pkg: _exit> python /usr/local/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: exit None (0.00 seconds) /builds/repo/dlproject> python /usr/local/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta pid=96
  docs: FAIL code -4 (361.24=setup[353.59]+cmd[7.65] seconds)
  evaluation failed :( (361.66 seconds)
Cleaning up project directory and file based variables
00:01
ERROR: Job failed: exit code 1

tox.ini:

# Tox configuration file
# Read more under https://tox.wiki/
# THIS SCRIPT IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS!

[tox]
minversion = 3.24
envlist = default
isolated_build = True


[testenv]
description = Invoke pytest to run automated tests
setenv =
    TOXINIDIR = {toxinidir}
passenv =
    HOME
    SETUPTOOLS_*
extras =
    testing
commands =
    pytest {posargs}


# # To run `tox -e lint` you need to make sure you have a
# # `.pre-commit-config.yaml` file. See https://pre-commit.com
# [testenv:lint]
# description = Perform static analysis and style checks
# skip_install = True
# deps = pre-commit
# passenv =
#     HOMEPATH
#     PROGRAMDATA
#     SETUPTOOLS_*
# commands =
#     pre-commit run --all-files {posargs:--show-diff-on-failure}


[testenv:{build,clean}]
description =
    build: Build the package in isolation according to PEP517, see https://github.com/pypa/build
    clean: Remove old distribution files and temporary build artifacts (./build and ./dist)
# https://setuptools.pypa.io/en/stable/build_meta.html#how-to-use-it
skip_install = True
changedir = {toxinidir}
deps =
    build: build[virtualenv]
passenv =
    SETUPTOOLS_*
commands =
    clean: python -c 'import shutil; [shutil.rmtree(p, True) for p in ("build", "dist", "docs/_build")]'
    clean: python -c 'import pathlib, shutil; [shutil.rmtree(p, True) for p in pathlib.Path("src").glob("*.egg-info")]'
    build: python -m build {posargs}
# By default, both `sdist` and `wheel` are built. If your sdist is too big or you don't want
# to make it available, consider running: `tox -e build -- --wheel`


[testenv:{docs,doctests,linkcheck}]
description =
    docs: Invoke sphinx-build to build the docs
    doctests: Invoke sphinx-build to run doctests
    linkcheck: Check for broken links in the documentation
passenv =
    SETUPTOOLS_*
setenv =
    DOCSDIR = {toxinidir}/docs
    BUILDDIR = {toxinidir}/docs/_build
    docs: BUILD = html
    doctests: BUILD = doctest
    linkcheck: BUILD = linkcheck
deps =
    -r {toxinidir}/docs/requirements.txt
    # ^  requirements.txt shared with Read The Docs
commands =
    sphinx-build -T -v --color -b {env:BUILD} -d "{env:BUILDDIR}/doctrees" "{env:DOCSDIR}" "{env:BUILDDIR}/{env:BUILD}" {posargs}


[testenv:publish]
description =
    Publish the package you have been developing to a package index server.
    By default, it uses testpypi. If you really want to publish your package
    to be publicly accessible in PyPI, use the `-- --repository pypi` option.
skip_install = True
changedir = {toxinidir}
passenv =
    # See: https://twine.readthedocs.io/en/latest/
    TWINE_USERNAME
    TWINE_PASSWORD
    TWINE_REPOSITORY
    TWINE_REPOSITORY_URL
deps = twine
commands =
    python -m twine check dist/*
    python -m twine upload {posargs:--repository {env:TWINE_REPOSITORY:testpypi}} dist/*

.gitlab-ci.yml:

# This file is a template, and might need editing before it works on your project.

stages:
  - prepare
  - test
  - deploy
  - release

variables:
  # Change cache dirs to be inside the project (can only cache local items)
  PIP_CACHE_DIR: $CI_PROJECT_DIR/.cache/pip
  PIPX_HOME: $CI_PROJECT_DIR/.cache/pipx
  PRE_COMMIT_HOME: $CI_PROJECT_DIR/.cache/pre-commit
  # Coveralls configuration
  CI_NAME: gitlab-ci
  CI_BRANCH: $CI_COMMIT_REF_NAME
  CI_BUILD_NUMBER: $CI_PIPELINE_ID
  CI_BUILD_URL: $CI_PIPELINE_URL
  # TODO: You will also need to set `COVERALLS_REPO_TOKEN` to work with coveralls.
  #       We recommend that you do that via GitLab CI web interface.
  # - https://coveralls-python.readthedocs.io/en/latest/usage/index.html
  # - https://docs.gitlab.com/ee/ci/variables/

workflow:
  rules:
    # Restrict the number of times the pipeline runs to save resources/limits
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      variables:
        # Specific merge request configurations for coveralls
        CI_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
        CI_PULL_REQUEST: $CI_MERGE_REQUEST_IID
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == 'push'
      when: never  # Avoid running the pipeline twice (push + merge request)
    - if: $CI_COMMIT_BRANCH || $CI_COMMIT_TAG
    # You can also set recurring execution of the pipeline, see:
    # https://docs.gitlab.com/ee/ci/pipelines/schedules.html

default:
  before_script:
    - python --version  # useful for debugging
    - apt-get install -yqq --no-install-recommends gcc
    # Setup git (used for setuptools-scm)
    - git config --global user.email "[email protected]"
    - git config --global user.name "Your Name"
    # Install dependencies for the testing environment
    - pip install -U pip tox pipx

check:
  stage: prepare
  image: "python:3.10-bullseye"
  script:
    - pipx run pre-commit run --all-files --show-diff-on-failure

build:
  stage: prepare
  image: "python:3.10-bullseye"
  script:
    - tox -v -e clean,build
  variables:
    GIT_DEPTH: "0"  # deep-clone
  artifacts:
    expire_in: 1 day
    paths: [dist]

.test_script: &test_script
  dependencies: [build]
  variables:
    COVERALLS_PARALLEL: "true"
    COVERALLS_FLAG_NAME: $CI_JOB_NAME
  script:
    - tox -v --installpkg dist/*.whl -- -rFEx --durations 10 --color yes
    - pipx run coverage xml -o coverage.xml
    #- pytest --cov --cov-report term --cov-report xml:coverage.xml
  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

py38:
  stage: test
  image: "python:3.8-bullseye"
  <<: *test_script

py39:
  stage: test
  image: "python:3.9-bullseye"
  <<: *test_script

py310:
  stage: test
  image: "python:3.10-bullseye"
  <<: *test_script

mamba:
  stage: test
  image: "condaforge/mambaforge"
  before_script:
    - mamba install -y pip pipx 'tox!=4.0.*,!=4.1.*' c-compiler cxx-compiler zlib
  <<: *test_script

#upload-coverage:
#  stage: deploy
#  image: "python:3.10"
#  script:
#    - pipx run coveralls --finish

deploy:
  stage: deploy
  dependencies: [build]
  image: "python:3.10"
  rules: [if: $CI_COMMIT_TAG]
  script:
    - tox -v -e build
    - tox -v -e publish

pages:
  stage: deploy
  cache: []
  image: "python:3.10-bullseye"
  script:
    - pip install tox pytest sphinx>=7.0 furo
    - tox -v -e docs
    - mv docs/_build/html public
  artifacts:
    paths:
      - public
#  only:
#    - main

7
  • 2
    The error message itself (FAIL code) is produced by tox: tox-dev/tox @ src/tox/session/cmd/run/common.py#_get_outcome_message(). Are you using tox with Sphinx?
    – VonC
    Commented May 27, 2023 at 20:51
  • @VonC yes I'm using it with tox. But why is it not possible to see why it fails 😬
    – gkcn
    Commented May 27, 2023 at 22:34
  • 2
    Could you please run tox in verbose mode in CI and show the complete output? Also please include both tox.ini and the gitlab config. Is your project open source? If yes, please include url. Commented May 28, 2023 at 5:02
  • @JürgenGmach Added tox.ini and gitlab-ci.yml, also -v flag to sphinx-build and updated it to 7.0 too. Project is not open source yet.
    – gkcn
    Commented May 29, 2023 at 17:23
  • Sorry I meant I ran tox in verbose mode by add -v option.
    – gkcn
    Commented May 30, 2023 at 0:09

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.