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?

Asked By: CiaranWelsh

||

Source

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.

Answered By: Steve Piercy

Answer 2

You can use nbsphinx-link.

On an easier structure:

|Project root
     |notebooks
           |sample.ipynb
     |docs
          |build
          |source

Install nbsphinx-link

pip install nbsphinx-link

add both nbsphinx and nbsphinx_link as extensions in your Sphinx build config, typicalyl in conf.py:

    extensions = [
       # ...
       # any other extensions you need,
       # ...
       'nbsphinx',
       'nbsphinx_link',
    ]

Add a .nblink file in source dir linking to your notebook.

    |Project root
     |notebooks
           |sample.ipynb
     |docs
          |build
          |source
               |sample.nblink

Add the path to the notebook in sample.nblink

{
"path": "relative/path/to/notebook"
}

Answered By: Azaria Gebremichael

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

Question:

Answers: