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). https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree — mzjn, Mar 22 '19 at 12:05
You can see a possible solution there: https://stackoverflow.com/questions/25866102/how-do-we-embed-images-in-sphinx-docs — Valtriz, Oct 01 '19 at 16:05

score 3 · Answer 1 · answered Dec 24 '21 at 15:55

I just ran in into this again and noticed that you need to make sure that your source_suffix config does not include .ipynb. So the conf.py should look like this

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

On top of that, you need to make sure that the notebook contains a title, as already pointed out in the answers above.

score 0 · Answer 2 · answered Apr 13 '20 at 09:08

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

2 Answers2