# Jupyter Notebook Tools for Sphinx

`nbsphinx` is a Sphinx extension that provides a source parser for `*.ipynb` files. Custom Sphinx directives are used to show Jupyter Notebook code cells (and of course their results) in both HTML and LaTeX output. Un-evaluated notebooks – i.e. notebooks without stored output cells – will be automatically executed during the Sphinx build process.

Quick Start:

  1. Install `nbsphinx`

  2. Edit your `conf.py` and add `'nbsphinx'` to `extensions`.

  3. Edit your `index.rst` and add the names of your `*.ipynb` files to the `toctree`.

  4. Run Sphinx!

Online documentation (and example of use):

  https://nbsphinx.readthedocs.io/

Source code repository (and issue tracker):

  https://github.com/spatialaudio/nbsphinx/

License:

  MIT – see the file `LICENSE` for details.

All of the following content was generated from Jupyter notebooks, except for the sections Normal reStructuredText Files, Contributing, References and Version History, which were generated from Sphinx’s built-in reStructuredText format.

click here to see full table of contents

- Installation
  - `nbsphinx` Packages
  - `nbsphinx` Prerequisites
    - Python
    - Sphinx
    - pip
    - pandoc
    - Pygments Lexer for Syntax Highlighting
    - Jupyter Kernel
- Usage
  - Project Setup
  - Running Sphinx
  - Watching for Changes with `sphinx-autobuild`
  - Automatic Creation of HTML and PDF output on readthedocs.org
    - Using `requirements.txt`
    - Using `conda`
  - Automatic Creation of HTML and PDF output on GitLab Pages
  - HTML Themes
    - Sphinx’s Built-In Themes
    - 3rd-Party Themes
  - Using Notebooks with Git
- Configuration
  - Sphinx Configuration Values
    - `exclude_patterns`
    - `extensions`
    - `html_css_files`
    - `html_sourcelink_suffix`
    - `latex_additional_files`
    - `mathjax3_config`
    - `pygments_style`
    - `suppress_warnings`
  - `nbsphinx` Configuration Values
    - `nbsphinx_allow_errors`
    - `nbsphinx_assume_equations`
    - `nbsphinx_codecell_lexer`
    - `nbsphinx_custom_formats`
    - `nbsphinx_epilog`
    - `nbsphinx_execute`
    - `nbsphinx_execute_arguments`
    - `nbsphinx_input_prompt`
    - `nbsphinx_kernel_name`
    - `nbsphinx_output_prompt`
    - `nbsphinx_prolog`
    - `nbsphinx_prompt_width`
    - `nbsphinx_requirejs_options`
    - `nbsphinx_requirejs_path`
    - `nbsphinx_responsive_width`
    - `nbsphinx_thumbnails`
    - `nbsphinx_timeout`
    - `nbsphinx_widgets_options`
    - `nbsphinx_widgets_path`
- Markdown Cells
  - Equations
    - Automatic Equation Numbering
    - Manual Equation Numbering
  - Citations
    - Footnote citations
  - Code
  - Tables
  - Images
    - Using the HTML `<img>` tag
    - SVG support for LaTeX
  - Cell Attachments
  - HTML Elements (HTML only)
  - Info/Warning Boxes
  - Links to Other Notebooks
  - Links to `*.rst` Files (and Other Sphinx Source Files)
  - Links to Local Files
  - Links to Domain Objects
- Code Cells
  - Code, Output, Streams
  - Special Display Formats
    - Local Image Files
    - Image URLs
    - Math
    - Plots
    - Pandas Dataframes
    - Markdown Content
    - YouTube Videos
    - Interactive Widgets (HTML only)
      - Troubleshooting
    - Arbitrary JavaScript Output (HTML only)
    - Unsupported Output Types
  - ANSI Colors
- Raw Cells
  - Usage
    - Jupyter Notebook
    - JupyterLab
  - Available Raw Cell Formats
    - None
    - reST
    - Markdown
    - HTML
    - LaTeX
    - Python
- Hidden Cells
- Controlling Notebook Execution
  - Pre-Executing Notebooks
    - Long-Running Cells
    - Rare Libraries
    - Exceptions
    - Client-specific Outputs
    - Interactive Input
  - Explicitly Dis-/Enabling Notebook Execution
  - Ignoring Errors
  - Ignoring Errors on a Per-Cell Basis
  - Configuring Kernels
    - Kernel Name
    - Kernel Arguments
    - Environment Variables
  - Cell Execution Timeout
- Prolog and Epilog
  - Examples
- Notebooks in Sub-Directories
  - A Sub-Section
  - That’s a “Strange” Section
- Creating Thumbnail Galleries
  - Gallery With Nested Documents
    - Last Image Is Used by Default
    - Using a Cell Tag to Select a Thumbnail
    - Using Cell Metadata to Select a Thumbnail and Provide a Tooltip
    - Choosing from Multiple Outputs
    - No Thumbnail Available
    - Specifying a Thumbnail File
  - Gallery With Links (HTML only)
- Using `toctree` In A Notebook
  - A Notebook that's just a "toctree" Target
  - An External Link (HTML only)
- Custom CSS
  - For All Pages
  - For All RST files
  - For All Notebooks
  - For a Single Notebook
- Normal reStructuredText Files
  - Links to Notebooks (and Other Sphinx Source Files)
  - Links to Notebooks, Ye Olde Way
  - Sphinx Directives for Info/Warning Boxes
  - Domain Objects
    - `example_python_function()`
  - References
    - Citations
    - Footnote citations
  - Thumbnail Link Galleries (HTML only)
  - Thumbnail Galleries
    - Dummy Notebook 1 for Gallery
- External Links
- Contributing
  - Development Installation
  - Building the Documentation
  - Building Themes
  - Testing
- References
- Version History

There is also An Orphan Notebook (HTML Only), just for the sake of it.