sphinx autodoc для python ничего не показывает (в readthedocs)

У меня есть этот пакет python, который я хотел бы автоматически документировать с помощью Sphinx. Я вставил строки документации во все функции и классы.

Я создал учетную запись на ReadTheDocs и сделал соответствующую настройку (т.е. каталог docs/ с файлом conf.py). Затем, в основном, я перепробовал почти все: каждую комбинацию autodoc::, autofunction::, autoclass::; Я пробовал использовать тот же conf.py файл в качестве других пакетов, которые документировали API (конечно, с конкретными изменениями, внесенными в соответствии с моим случаем); но это просто не работает, страница API неумолимо остается пустой ...


python api python-sphinx autodoc read-the-docs
person Dominique Makowski    schedule 15.11.2016    source источник
comment
И если вы перейдете на страницу сборки в RTD (https://readthedocs.org/projects/<your-project>/builds/), получите ли вы там какие-либо отзывы? Как вы создали api.rst? Я считаю это полезным для начальной настройки: jeffknupp.com/blog/2013/08/16/   -  person jonrsharpe    schedule 15.11.2016
comment
Спасибо за эту очень полезную ссылку! Однако, хотя я попытался воспроизвести эти шаги и попытался создать документацию с нуля, он все равно ничего не показывает. Хуже всего то, что когда я запускаю make-файл (используя команду make html, он не показывает никакой конкретной ошибки и ничего, связанного с пакетом, который я пытаюсь задокументировать ...). Я просто не могу понять почему! Что касается моего api.rst файла, он был сгенерирован только путем создания первого документа и вставки некоторых ..autoclass:: директив. В любом случае спасибо за ответ!   -  person Dominique Makowski    schedule 17.11.2016
comment
Это может быть проблемой, думали ли вы о том, чтобы Sphinx генерировал документы, а не пытался сделать это самостоятельно?   -  person jonrsharpe    schedule 17.11.2016

Ответы (1)


arrow_upward
0
arrow_downward

Попробуйте добавить это в свой conf.py:

########### TRICK FOUND ON SOME TUTORIAL : ADD IN THE MOCK_MODULES ANY EXTERNAL MODULE YOU'RE USING IN YOUR PACKAGE.

import mock

MOCK_MODULES = ['numpy', 'scipy', 'sklearn', 'matplotlib', 'matplotlib.pyplot', 'scipy.interpolate', 'scipy.special', 'math', '__future__', 'toolboxutilities']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

В MOCK_MODULES добавьте любой единственный внешний импорт, который использует ваш проект. У меня была точно такая же проблема, и это решило ее.

Также в conf.py не забудьте добавить:

sys.path.insert(0, os.path.abspath('../..'))

В вашем случае он у вас уже есть, но я упоминаю об этом на тот случай, если кто-то еще с такой же проблемой увидит мой ответ.

person Guillaume    schedule 10.12.2016