Блог

Я пытаюсь сгенерировать документацию Sphinx для проекта с использованием Poetry и Tox. У меня такая конфигурация:

 # tox.ini
[tox]
envlist = py36
isolated_build = True

[tox:.package]
basepython = python3

[testenv]
whitelist_externals = poetry
commands =
    poetry install -v
    poetry run pytest tests/

[testenv:docs]
description = invoke sphinx-build to build the HTML docs
whitelist_externals = poetry
commands = poetry run sphinx-build -d "{toxworkdir}/docs_doctree" documentation/source "{toxworkdir}/docs_out" --color -bhtml {posargs}
           python -c 'import pathlib; print("documentation available under file://{0}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'
  

 # pyproject.toml
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "my-project"
version = "0.0.1"
description = "My project"

[tool.poetry.dependencies]
python = "^3.6"
apache-beam = {extras = ["gcp"], version = "^2.24.0"}
click = "^7.1"
click-log = "^0.3"

[tool.poetry.dev-dependencies]
pytest = "^6.1"
black = "20.8b1"
sphinx = "^3.2.1"
sphinx-autoapi = "^1.5"
  

Локально я могу запустить следующие командные строки для создания документации, все они работают:

• cd documentation; make html
• tox -e docs

Но для CI в Bamboo я решил запускать в контейнере Docker (ИЗ python: 3.6 с установленными Poetry и Tox), чтобы избежать проблем с другими пакетами, установленными на агенте, а затем tox -e docs выдает ошибку:

  docs run-test: commands[0] | poetry run sphinx-build -d /app/.tox/docs_doctree documentation/source /app/.tox/docs_out --color -bhtml

  FileNotFoundError

  [Errno 2] No such file or directory
 
   at /usr/local/lib/python3.6/os.py:594 in _execvpe
        590│         path_list = map(fsencode, path_list)
        591│     for dir in path_list:
        592│         fullname = path.join(dir, file)
        593│         try:
     →  594│             exec_func(fullname, *argrest)
        595│         except OSError as e:
        596│             last_exc = e
        597│             tb = sys.exc_info()[2]
        598│             if (e.errno != errno.ENOENT and e.errno != errno.ENOTDIR
 ERROR: InvocationError for command /usr/local/bin/poetry run sphinx-build -d .tox/docs_doctree documentation/source .tox/docs_out --color -bhtml (exited > with code 1)
  

Если я запускаю a docker exec для получения интерактивной оболочки в контейнере и запуска /usr/local/bin/poetry run sphinx-build -d .tox/docs_doctree documentation/source .tox/docs_out --color -bhtml , создается документация.

Я не могу найти причину этой ошибки. Я нашел обходной путь, поместив зависимости sphinx непосредственно в конфигурацию Tox, но теперь у меня есть зависимости в обоих файлах, и я хотел бы понять, что произошло:

 deps =
    sphinx == 3.2.1
    sphinx-autoapi == 1.5.1
commands = poetry run sphinx-build -d "{toxworkdir}/docs_doctree" documentation/source "{toxworkdir}/docs_out" --color -bhtml {posargs}
           python -c 'import pathlib; print("documentation available under file://{0}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'
  

С первого взгляда я бы сказал:

commands Параметр в [testenv:docs] перезаписывает параметр from [testenv] . Поэтому я предполагаю, что предполагается, что poetry install -v это было запущено в docs тестовой среде, но это не так. В любом случае sphinx (и другие зависимости) не устанавливаются в docs тестовой среде.

Возможно, вы захотите добавить некоторый вариант poetry install в верхней части commands настройки [testenv:docs] .