Заставить sphinx-build вызывать исключения, чтобы IDE могла их перехватить?

Question

При попытке исправить ошибку сборки Sphinx было бы крайне полезно, чтобы моя среда IDE сбрасывалась в точку останова при перехвате исключения. Однако кажется, что sphinx-build перехватывает исключения, а затем не полностью выводит их в IDE. Есть ли способ указать sphinx-build полностью вызвать исключение?

Более конкретно, в моей IDE (PyCharm) у меня есть конфигурация запуска для запуска sphinx-build. Если я добавлю точку останова в Sphinx conf.py, отладчик корректно переместится в точку останова. С включенным перехватом исключений в среде IDE я ожидаю, что среда IDE перейдет в точку останова для исключения (как это происходит при любом другом запуске Python). Однако похоже, что sphinx-build перехватывает исключение, печатает свое собственное сообщение об ошибке вывода и не вызывает дальнейшего исключения. Похоже, что он делает это, чтобы он мог вывести свое собственное сообщение после ошибки. Поскольку исключение не возникает, среда IDE не может его перехватить. Есть ли способ заставить sphinx-build полностью поднять все исключения? Я не могу найти вариант в обычных sphinx-build аргументах . Или есть другой обходной путь?

Answer 1

Это должно быть возможно при запуске процесса сборки sphinx непосредственно из скрипта python, как показано в этом ответе .

Answer 2

@ Ответ Xukrao указал мне верное направление, но я хотел дать более подробный ответ для будущих читателей.

Решение

Используйте свою собственную сборку Sphinxскрипт. Например,

from pathlib import Path
from sphinx.application import Sphinx

docs_directory = Path('.').absolute()
source_directory = docs_directory
configuration_directory = docs_directory
build_directory = Path(configuration_directory, '_build')
doctree_directory = Path(build_directory, '.doctrees')
builder = 'html'

app = Sphinx(source_directory, configuration_directory, build_directory, doctree_directory, builder)
app.build()

В этом случае исходный код находится в корневом каталоге проекта, а файл conf.py находится в каталоге docs в корневом каталоге проекта. Путь к исходному коду добавляется в conf.py. Здесь мы сами создаем приложение Sphinx Builder и передаем в соответствующие каталоги.

Пояснение

С версией sphinx-build на момент написания, этоневозможно получить скрипт для поднятия исключений. Это связано с тем, что любой вызов sphinx-build и связанных скриптов в итоге вызывает функцию build_main пакета Sphinx. Эта функция делает что-то похожее на наш пользовательский скрипт сборки выше, но она оборачивает весь вызов в оператор try/except, который перехватывает все исключения. Затем скрипт вручную обрабатывает исключения, печатая наши ошибки и связанную с ними информацию. Однако эта обработка не вызывает (и не имеет возможности повысить) исключение вверх. Таким образом, для текущей версии Sphinx исключения sphinx-build никогда не смогут достичь IDE.