Including ipynb files in sphinx index.rst when they are located in a subdirectory

Question

I am stuck with pythons sphinx. My directory tree looks like this:

| - project_root
|    | - importable_project
|    |    | - importable_module.py
|    |    | - another_importable_module.py
|    |    | - Tutorials
|    |    |    | - tutorial1.ipynb
|    | - docs
|    |    | - build
|    |    |    | - sphinx_build_files_and_folders
|    |    | - source
|    |    |    | - _static
|    |    |    | - _templates
|    |    |    | - conf.py
|    |    |    | - index.rst
|    |    |    | - modules.rst

I have enabled the nbsphinx extention as per the instructions and I'm modifying the index.rst file within the source folder.

Here is what the index.rst file currently looks like:

.. Pycotools documentation master file, created by
   sphinx-quickstart on Wed Oct 11 11:46:06 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Pycotools's documentation!
=====================================

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

   /modules
   ../../importable_project/Tutorials/tutorial1


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

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

Most of this was automatically generated by sphinx-quickstart. I understand that file paths specified here are relative to the location of the index.rst file. So in this case project_root/docs/source and sphinx is able to generate html for moudles.rst with the index.rst file above.

The problem is that I would like to include my tutorials in the documentation but the line ../../importable_project/Tutorials/tutorial1 is not able to locate tutorial1.ipynb.

Can anybody suggest what I'm doing wrong?

Answer 1

Tutorials are documentation, and should be moved into the docs/source directory. Sphinx cannot find files outside of its source directory, except for packages via autodoc. You'll need to adjust your path accordingly after moving the .ipynb file.