Ошибка несуществующего документа в Sphinx

Question

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

Я использовал sphinx-quickstart, чтобы все настроить. Я использовал "doc/" для корневого расположения документации. Папка, содержащая мой пакет, настроена как:

myfolder/
    doc/
    mypackage/
        __init__.py
        moprob.py
        ...

После быстрого запуска я отредактировал путь в conf.py, чтобы он был:

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

Затем я добавил один из сценариев в своем пакете в index.rst, чтобы увидеть, как работает sphinx.

 .. toctree::
   :maxdepth: 2
   :caption: Contents:

   mypackage/moprob

Код ошибки, который я получаю:

.../index.rst:9: WARNING: toctree contains reference to nonexisting document u'mypackage/moprob'

Решения, которые я попробовал:

1. Добавление sphinx.ext.napoleon в список расширений, так как все мои строки документа написаны в формате numpy. Ошибка не ушла. Я также поместил расширение наполеона после autodoc, потому что одна из страниц помощи предложила это.

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

2. Добавление numpydoc_show_class_members = False в conf.py. Я положил это прямо под расширениями. Это тоже не помогло.

3. Пара различных конфигураций для расположения папок. Я также попытался установить корневую папку для myfolder, а для источника - my package, а для сборки - doc. Никто не работал.

У вас есть идея, которая может мне помочь?

Answer 1

Директива toctree содержит ссылки на документы reStructuredText, а не на скрипты Python или модули. Sphinx ожидает, что будет файл mypackage/moprob.rst (в папке doc), но его нет. Отсюда и ошибка.

Чтобы быстро получить значимый вывод, создайте файл mypackage/moprob.rst. Добавьте в него заголовок и директиву автомодуля:

moprob module
=============

.. automodule:: mypackage.moprob
   :members:

Затем снова запустите sphinx-build.