Jupyter notebook does not rendered with sphinx

Question

I am using sphinx to document a python project. I want to add some tutorial as *.ipynb. I have a problem about how to render jupyter notebook. Here is my code.

I created a docs folder and all sphinx command will run under this folder. Below is the structure of my roject

demos/
src/
docs/
  source/
     config.py
     demos.rst
     modules.rst
     src.rst
     index.rst
     ....
  build/

here is the content of demos.rst

Demonstration
=============

demos.tuto1
----------------------
demos/tuto1.ipynb

demos.tuto2
-------------------
demos/tuto2.ipynb

here is the content of the index.rst

Welcome to my python project
============================

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

   modules
   src
   demos


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

In config.py file:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autodoc', 'nbsphinx']
nbsphinx_execute = 'never'
nbsphinx_allow_errors = True
source_suffix = ['.rst', '.ipynb']
html_theme = 'sphinx_rtd_theme'

When I run make html I render everything except the jupyter notebook. What does I miss?

Answer 1

You confused syntax between two different contexts.

If you have a toctree entry context, such as in your index.rst , then you can do this:

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

    modules
    src
    demos/tuto1.ipynb
    demos/tuto2.ipynb

If you want to have a separate"normal reST file" , then you can do this:

.. _link: demos/tuto1.ipynb