RST file generator

Generate the rst files for the examples by iterating over the python example files.

Files that generate images should start with ‘plot’



Remove “unload” seaborn from the name space

After a script is executed it can load a variety of setting that one does not want to influence in other examples in the gallery.

sphinx_gallery.gen_rst.codestr2rst(codestr, lang='python')

Return reStructuredText code block from code string

sphinx_gallery.gen_rst.execute_code_block(code_block, example_globals, block_vars, gallery_conf)

Executes the code block of the example file


Extract the first paragraph of module-level docstring. max:95 char


Pull out the thumbnail image number specified in the docstring.

sphinx_gallery.gen_rst.figure_rst(figure_list, sources_dir)

Given a list of paths to figures generate the corresponding rst

Depending on whether we have one or more figures, we use a single rst call to ‘image’ or a horizontal list.

  • figure_list (list of str) – Strings are the figures’ absolute paths
  • sources_dir (str) – absolute path of Sphinx documentation sources

  • images_rst (str) – rst code to embed the images in the document
  • fig_num (int) – number of figures saved

sphinx_gallery.gen_rst.generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs)

Generate the gallery reStructuredText for an example directory

sphinx_gallery.gen_rst.generate_file_rst(fname, target_dir, src_dir, gallery_conf)

Generate the rst file for a given example.

  • amount_of_code (int) – character count of the corresponding python script in file
  • time_elapsed (float) – seconds required to run the script

Separate filename content between docstring and the rest

Strongly inspired from ast.get_docstring.

  • docstring (str) – docstring of filename
  • rest (str) – filename content without the docstring

Returns md5sum of file


Returns path to packaged static files

sphinx_gallery.gen_rst.indent(text, prefix, predicate=None)

Adds ‘prefix’ to the beginning of selected lines in ‘text’.

If ‘predicate’ is provided, ‘prefix’ will only be added to the lines where ‘predicate(line)’ is True. If ‘predicate’ is not provided, it will default to adding ‘prefix’ to all non-empty lines that do not consist solely of whitespace characters.


Generate a Jupyter notebook file cell-by-cell

Parameters:script_blocks (list) – script execution cells

Checks whether src_file has the same md5 hash as the one on disk

sphinx_gallery.gen_rst.save_figures(image_path, fig_count, gallery_conf)

Save all open matplotlib figures of the example code-block

  • image_path (str) – Path where plots are saved (format string which accepts figure number)
  • fig_count (int) – Previous figure number count. Figure number add from this number
  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery

  • images_rst (str) – rst code to embed the images in the document
  • fig_num (int) – number of figures saved

sphinx_gallery.gen_rst.save_notebook(work_notebook, write_file)

Saves the Jupyter work_notebook to write_file

sphinx_gallery.gen_rst.save_thumbnail(image_path_template, src_file, gallery_conf)

Save the thumbnail image

sphinx_gallery.gen_rst.scale_image(in_fname, out_fname, max_width, max_height)

Scales an image with the same aspect ratio centered in an image with a given max_width and max_height if in_fname == out_fname the image can only be scaled down


Return list with source file separated into code and text blocks.

Returns:blocks – List where each element is a tuple with the label (‘text’ or ‘code’), and content string of block.
Return type:list of (label, content)
sphinx_gallery.gen_rst.time() → floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

sphinx_gallery.gen_rst.write_backreferences(seen_backrefs, gallery_conf, target_dir, fname, snippet)

Writes down back reference files, which include a thumbnail list of examples using a certain module


class sphinx_gallery.gen_rst.MixedEncodingStringIO

Helper when both ASCII and unicode strings will be written

class sphinx_gallery.gen_rst.StringIO

Text I/O implementation using an in-memory buffer.

The initial_value argument sets the value of object. The newline argument is like the one of TextIOWrapper’s constructor.


Close the IO object.

Attempting any further operation after the object is closed will raise a ValueError.

This method has no effect if the file is already closed.


Retrieve the entire contents of the object.


Read at most size characters, returned as a string.

If the argument is negative or omitted, read until EOF is reached. Return an empty string at EOF.


Returns True if the IO object can be read.


Read until newline or EOF.

Returns an empty string if EOF is hit immediately.


Change stream position.

Seek to character offset pos relative to position indicated by whence:
0 Start of stream (the default). pos should be >= 0; 1 Current position - pos must be 0; 2 End of stream - pos must be 0.

Returns the new absolute position.


Returns True if the IO object can be seeked.


Tell the current file position.


Truncate size to pos.

The pos argument defaults to the current file position, as returned by tell(). The current file position is unchanged. Returns the new absolute position.


Returns True if the IO object can be written.


Write string to file.

Returns the number of characters written, which is always equal to the length of the string.

class sphinx_gallery.gen_rst.Tee(file1, file2)

A tee object to redirect streams to multiple outputs


alias of str


alias of str