CODEWITHSUNDEEP
pythondirectorypython-sphinxsubdirectory
CiaranWelsh
CiaranWelsh

Reputation: 7681

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

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?

Upvotes: 0

Views: 892

Answers (2)

Azaria Gebremichael
Azaria Gebremichael

Reputation: 762

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"
}

Link .nblink file in your index.rst then should work

Upvotes: 0

Steve Piercy
Steve Piercy

Reputation: 15035

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.

Upvotes: 3

Related Questions