Including notebook with nbsphinx fails

Question

I am new to Sphinx and I want to write a documentation of a Python package. I have a problem when I want to include a demonstration file.

I want to include the file demo.ipynb using the extension nbsphinx. It is successfully installed on my computer. The extensions variable in my conf.py file for Sphinx contains the following lines:

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

and the toctree in my index.rst is the following:

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

   demo

when I compile my documentation I always obtain the following warning:

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

Does Sphinx maybe try to include the file as .rst file? The nbsphinx documentation just says that I have to install the package, add nbsphinx to the extensions and that I will then be able to add my documents to the toctree. I didn't find any information related to this problem.

Toctree entries are supposed to be RST files (with a title/heading). sphinx-doc.org/en/master/usage/restructuredtext/… — mzjn
You can see a possible solution there: stackoverflow.com/questions/25866102/… — Valtriz

Matthias Matthias · Accepted Answer · 2020-04-13T09:08:35

Each notebook needs a title.

Just create a Markdown cell in your notebook with something like this in it:

# My Title

See also https://github.com/spatialaudio/nbsphinx/issues/310 and https://github.com/spatialaudio/nbsphinx/pull/401.

There is now a better warning, see https://github.com/spatialaudio/nbsphinx/pull/402.

Including notebook with nbsphinx fails

1 Answers