Не удается включить ноутбук с nbsphinx

Question

Я новичок в sphinx, и я хочу написать документацию пакета Python. У меня проблема, когда я хочу включить демонстрационный файл. Я хочу включить файл demo.ipynb, используя расширение nbsphinx. Он успешно установлен на моем компьютере. Переменная extensions в моем файле conf.py для sphinx содержит следующие строки:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.napoleon',
    'nbsphinx',
]

и toctree в моем index.rst выглядит следующим образом:

.. toctree::
   :maxdepth: 3
   :glob:

   demo

когда я собираю свою документацию, я всегда получаю следующее предупреждение:

PATHTOPACKAGE/docs/source/index.rst:19: WARNING: toctree contains reference to document 'demo' that doesn't have a title: no link will be generated

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

Answer 1

Я только что снова столкнулся с этим и заметил, что вам нужно убедиться, что ваш source_suffixконфиг не входит .ipynb. Итак conf.pyдолжно выглядеть так

      extensions = [
    # ...,
    "nbsphinx"
]
source_suffix = [".rst", ".md"]
# note: do not add .ipynb when nbspinx is enabled, otherwise you get the "missing title" error

Кроме того, вам нужно убедиться, что блокнот содержит заголовок, как уже указывалось в ответах выше.

Answer 2

Каждой записной книжке нужно название.

Просто создайте в своем блокноте ячейку Markdown, в которой будет что-то вроде этого:

# My Title

См. Также https://github.com/spatialaudio/nbsphinx/issues/310 и https://github.com/spatialaudio/nbsphinx/pull/401.

Теперь есть лучшее предупреждение, см. https://github.com/spatialaudio/nbsphinx/pull/402.