# sphinx_gallery.notebook

Parser for Jupyter notebooks.

Class that holds the Jupyter notebook information

## Functions

sphinx_gallery.notebook.add_code_cell(work_notebook: dict[str, Any], code: str) → None

  Add a code cell to the notebook.

  Parameters:

    code (str) – Cell content

sphinx_gallery.notebook.add_markdown_cell(work_notebook: dict[str, Any], markdown: str) → None

  Add a markdown cell to the notebook.

  Parameters:

    markdown (str) – Markdown cell content.

sphinx_gallery.notebook.convert_code_to_md(text: str) → str

  Rewrite code blocks to use Markdown’s preferred backtick notation.

  Backtick notation preserves syntax highlighting.

  Parameters:

    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: Match, directive: str) → str

  Helper to fill in directives.

sphinx_gallery.notebook.fill_notebook(work_notebook: dict[str, Any], script_blocks: list[Block], gallery_conf: dict[str, Any], target_dir: str) → None

  Writes the Jupyter notebook cells.

  If available, uses pypandoc to convert rst to markdown.

  Parameters:

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

sphinx_gallery.notebook.generate_image_src(image_path: str, gallery_conf: dict[str, Any], target_dir: str) → str

  Modify image path for notebook, according to “notebook_images” config.

  URLs are unchanged. If “notebook_images” config is a str, it is used as a prefix to image path, relative to “src_dir”. If “notebook_images” is True, image is embedded as URI. If “notebook_images” is False, “file://” is prepended.

sphinx_gallery.notebook.jupyter_notebook(script_blocks: list[Block], gallery_conf: dict[str, Any], target_dir: str) → dict[str, Any]

  Generate a Jupyter notebook file cell-by-cell.

  Parameters:

    - 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.

sphinx_gallery.notebook.jupyter_notebook_skeleton() → dict[str, Any]

  Returns a dictionary with the elements of a Jupyter notebook.

sphinx_gallery.notebook.promote_jupyter_cell_magic(work_notebook: dict[str, Any], markdown: str) → str

  Promote Jupyter cell magic in text blocks to code block in notebooks.

  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.

  Parameters:

    markdown (str) – Markdown cell content.

sphinx_gallery.notebook.python_to_jupyter_cli(args=None, namespace=None, sphinx_gallery_conf=None)

  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: str, gallery_conf: dict[str, Any], target_dir: str, heading_levels: dict[tuple[str | None, str], int]) → str

  Converts reST from docstrings and text blocks to markdown for Jupyter notebooks.

  Parameters:

    - 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: dict[str, Any], write_file: str | Path) → None

  Saves the Jupyter work_notebook to write_file.