Using Jupyter Notebooks¶

For basic information on using nbsphinx extension, please refer to the official documentation. This guide focuses on advanced techniques for integrating Jupyter Notebooks with DocFly framework for Sphinx documentation.

Using RestructuredText in Jupyter Notebooks¶

Jupyter Notebook primarily uses Markdown, but you can still use RestructuredText (RST) or Sphinx syntax in a Notebook by using Raw cells:

Create a new cell and change its type to “Raw”
Click the “COMMON TOOLS” button
Set “Raw NBConvert Format” to “ReStructured Text”

Document Title Setup¶

When setting up a document title that can be properly detected by nbsphinx for table of contents, use this pattern in a Raw cell:

.. _unique-reference-id:

Document Title
================================================================================

The JSON representation of this cell in the notebook file will be:

{
 "cell_type": "raw",
 "id": "d1454a25-eb5f-4eb3-b5fb-f1ac1f012b18",
 "metadata": {
  "editable": true,
  "raw_mimetype": "text/restructuredtext", // <--- mimitype
  "slideshow": {
   "slide_type": ""
  },
  "tags": []
 },
 "source": [
  ".. _unique-reference-id:\n",
  "\n",
  "Document Title\n",
  "================================================================================\n",
  "..."
 ]
},

⚠️ Known Issue: Since January 2, 2025, nbsphinx has a bug that prevents proper TOC link creation for Jupyter Notebooks when using RestructuredText cells as document titles. See GitHub PR #834 for details.

Cross-Referencing Documents¶

To create references between documents using Sphinx’s :ref: cross reference syntax:

Reference this point from any other document:¶

Define a reference point in any RST content:

.. _unique-ref-link:

Any Content

Reference this point from any other document:

See :ref:`unique-ref-link` for more information.

[ ]: