Parser for Jupyter notebooks#

Class that holds the Jupyter notebook information


sphinx_gallery.notebook.add_code_cell(work_notebook, code)[source]#

Add a code cell to the notebook


code (str) – Cell content

sphinx_gallery.notebook.add_markdown_cell(work_notebook, markdown)[source]#

Add a markdown cell to the notebook


markdown (str) – Markdown cell content.


Rewrites code blocks using the code-block notation to use Markdown’s preferred backtick notation, which preserves syntax highlighting.


text (str) – A mostly converted string of markdown text. May contain zero, one, or multiple code blocks in code-block format.

sphinx_gallery.notebook.directive_fun(match, directive)[source]#

Helper to fill in directives

sphinx_gallery.notebook.fill_notebook(work_notebook, script_blocks, gallery_conf, target_dir)[source]#

Writes the Jupyter notebook cells

If available, uses pypandoc to convert rst to markdown.


script_blocks (list) – Each list element should be a tuple of (label, content, lineno).

sphinx_gallery.notebook.generate_image_src(image_path, gallery_conf, target_dir)[source]#
sphinx_gallery.notebook.jupyter_notebook(script_blocks, gallery_conf, target_dir)[source]#

Generate a Jupyter notebook file cell-by-cell

  • script_blocks (list) – Script execution cells.

  • gallery_conf (dict) – The sphinx-gallery configuration dictionary.

  • target_dir (str) – Path that notebook is intended for. Used where relative paths may be required.


Returns a dictionary with the elements of a Jupyter notebook

sphinx_gallery.notebook.promote_jupyter_cell_magic(work_notebook, markdown)[source]#

Parses a block of markdown text looking for code blocks starting with a Jupyter cell magic (e.g. %%bash). Whenever one is found, the text before it and the code (as a runnable code block) are added to work_notebook. Any remaining text is returned.


markdown (str) – Markdown cell content.

sphinx_gallery.notebook.python_to_jupyter_cli(args=None, namespace=None, sphinx_gallery_conf=None)[source]#

Exposes the jupyter notebook renderer to the command line

Takes the same arguments as ArgumentParser.parse_args. sphinx_gallery_conf functions same as in conf.py.

sphinx_gallery.notebook.rst2md(text, gallery_conf, target_dir, heading_levels)[source]#

Converts the reST text from the examples docstrings and comments into markdown text for the Jupyter notebooks

  • text (str) – reST input to be converted to MD

  • gallery_conf (dict) – The sphinx-gallery configuration dictionary.

  • target_dir (str) – Path that notebook is intended for. Used where relative paths may be required.

  • heading_levels (dict) – Mapping of heading style (over_char, under_char) to heading level. Note that over_char is None when only underline is present.

sphinx_gallery.notebook.save_notebook(work_notebook, write_file)[source]#

Saves the Jupyter work_notebook to write_file