sphinx autodoc создает пустую страницу в readthedocs, но правильно включает локальную строку документации модуля - PullRequest
Новая
       52

sphinx autodoc создает пустую страницу в readthedocs, но правильно включает локальную строку документации модуля

0 голосов
/ 21 мая 2019

Когда я запускаю sphinx локально (версии 1.6.6 или 2.0.1 на Anaconda Python 3.6.8 для Mac), я получаю другие результаты, чем когда я запускаю его на readthedocs.org (согласно их журналу это Sphinx)версия 1.8.5 и, вероятно, Python 2.7, поскольку он запускается с python вместо python3).

Разница заключается в результатах из следующего файла Shady.Text.rst, который содержит не более:

Shady.Text Sub-module
=====================

.. automodule:: Shady.Text

Теперь этот субмодуль содержит только строку документации уровня модуля и не содержит строки документа члена - это так, как задумано, поэтому соответствующая html-страница должна содержать строку документа ибольше не надо.И это именно то, что происходит, когда я запускаю make html локально.Однако результат в https://shady.readthedocs.io/en/latest/source/Shady.Text.html не содержит содержимого (только заголовок, без строки документа).

FWIW Мои записи, связанные с автодоком, в conf.py: 

autoclass_content = 'both'
autodoc_member_order = 'groupwise'

Что я делаю не так?

1 Ответ

0 голосов
/ 21 мая 2019

Спасибо @StevePiercy за то, что обратили мое внимание на важные строки в файле необработанного журнала: 

WARNING: autodoc: failed to import module u'Text' from module u'Shady'; the module executes module level statement and it might call sys.exit().
WARNING: autodoc: failed to import module u'Video' from module u'Shady'; the module executes module level statement and it might call sys.exit().

(я искал в 9000-строчном файле журнала .Text, потому что Text создает слишком много обращений, но мне не пришло в голову искать его 'Text' в кавычках).

Для меня это сообщение вводит в заблуждение: проблема не в том, что «модуль выполняет операторы уровня модуля», потому что per se разрешено. Я потратил некоторое время после того, как заметил, что некоторые операторы уровня модуля, по-видимому, разрешены в других подмодулях, и попытался связать нарушающие операторы уровня модуля в декоратор класса, думая, что, возможно, таинственный модуль-уровень Сфинкса - тогда детектор выписок пропустит их ...)

Нет, проблема в том, что не факт, что операторы уровня модуля существуют и может вызвать sys.exit(), а тот факт, что они действительно косвенно вызвали sys.exit() во время процедура компиляции сфинкса. Это был изворотливый способ обработки недостающих зависимостей, который, вероятно, следует переосмыслить, но я мог бы обойти это сейчас, избегая моего звонка sys.exit(), когда os.environ.get('READTHEDOCS') правдив.

...