sphinx_gallery.gen_rst

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

Functions

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

Return reStructuredText code block from code string

sphinx_gallery.gen_rst.executable_script(src_file, gallery_conf)

Validate if script has to be run according to gallery configuration

Parameters:
  • src_file (str) – path to python script
  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery
Returns:

True if script has to be executed

Return type:

bool

sphinx_gallery.gen_rst.execute_code_block(compiler, block, example_globals, block_vars, gallery_conf)

Executes the code block of the example file

sphinx_gallery.gen_rst.execute_script(script_blocks, script_vars, gallery_conf)

Execute and capture output from python script already in block structure

Parameters:
  • script_blocks (list) – (label, content, line_number) List where each element is a tuple with the label (‘text’ or ‘code’), the corresponding content string of block and the leading line number
  • script_vars (dict) – Configuration and run time variables
  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery
Returns:

  • output_blocks (list) – List of strings where each element is the restructured text representation of the output of each block
  • time_elapsed (float) – Time elapsed during execution

sphinx_gallery.gen_rst.extract_intro_and_title(filename, docstring)

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

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.

Parameters:
  • fname (str) – Filename of python script
  • target_dir (str) – Absolute path to directory in documentation where examples are saved
  • src_dir (str) – Absolute path to directory where source examples are stored
  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery
Returns:

  • intro (str) – The introduction of the example
  • time_elapsed (float) – seconds required to run the script

sphinx_gallery.gen_rst.get_md5sum(src_file)

Returns md5sum of file

sphinx_gallery.gen_rst.handle_exception(exc_info, src_file, block_vars, gallery_conf)
sphinx_gallery.gen_rst.md5sum_is_current(src_file)

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

sphinx_gallery.gen_rst.rst_blocks(script_blocks, output_blocks, file_conf, gallery_conf)

Generates the rst string containing the script prose, code and output

Parameters:
  • script_blocks (list) – (label, content, line_number) List where each element is a tuple with the label (‘text’ or ‘code’), the corresponding content string of block and the leading line number
  • output_blocks (list) – List of strings where each element is the restructured text representation of the output of each block
  • file_conf (dict) – File-specific settings given in source file comments as: # sphinx_gallery_<name> = <value>
  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery
Returns:

out – rst notebook

Return type:

str

sphinx_gallery.gen_rst.save_rst_example(example_rst, example_file, time_elapsed, gallery_conf)

Saves the rst notebook to example_file including necessary header & footer

Parameters:
  • example_rst (str) – rst containing the executed file content
  • example_file (str) – Filename with full path of python example file in documentation folder
  • time_elapsed (float) – Time elapsed in seconds while executing file
  • gallery_conf (dict) – Sphinx-Gallery configuration dictionary
sphinx_gallery.gen_rst.save_thumbnail(image_path_template, src_file, file_conf, gallery_conf)

Generate and Save the thumbnail image

Parameters:
  • image_path_template (str) – holds the template where to save and how to name the image
  • src_file (str) – path to source python file
  • gallery_conf (dict) – Sphinx-Gallery configuration dictionary

Classes

class sphinx_gallery.gen_rst.LoggingTee(output_file, logger, src_filename)

A tee object to redirect streams to the logger

class sphinx_gallery.gen_rst.MixedEncodingStringIO

Helper when both ASCII and unicode strings will be written

write(data)

Write string to file.

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