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.

Examples using sphinx_gallery.gen_rst.codestr2rst

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

Examples using sphinx_gallery.gen_rst.executable_script

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

Execute the code block of the example file.

Examples using sphinx_gallery.gen_rst.execute_code_block

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

Examples using sphinx_gallery.gen_rst.execute_script

sphinx_gallery.gen_rst.extract_intro_and_title(filename, docstring)

Extract and clean the first paragraph of module-level docstring.

Examples using sphinx_gallery.gen_rst.extract_intro_and_title

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

Generate the gallery reStructuredText for an example directory.

Examples using sphinx_gallery.gen_rst.generate_dir_rst

sphinx_gallery.gen_rst.generate_file_rst(fname, target_dir, src_dir, gallery_conf, seen_backrefs=None)

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

• seen_backrefs (set) – The seen backreferences.

Returns

• intro (str) – The introduction of the example

• cost (tuple) – A tuple containing the (time, memory) required to run the script.

Examples using sphinx_gallery.gen_rst.generate_file_rst

sphinx_gallery.gen_rst.handle_exception(exc_info, src_file, script_vars, gallery_conf)

Trim and format exception, maybe raise error, etc.

Examples using sphinx_gallery.gen_rst.handle_exception

sphinx_gallery.gen_rst.md5sum_is_current(src_file, mode='b')

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

Examples using sphinx_gallery.gen_rst.md5sum_is_current

sphinx_gallery.gen_rst.patch_warnings()

Patch warnings.showwarning to actually write out the warning.

Examples using sphinx_gallery.gen_rst.patch_warnings

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

Generate 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

Examples using sphinx_gallery.gen_rst.rst_blocks

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

Saves the rst notebook to example_file including 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

• memory_used (float) – Additional memory used during the run.

• gallery_conf (dict) – Sphinx-Gallery configuration dictionary

Examples using sphinx_gallery.gen_rst.save_rst_example

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

Examples using sphinx_gallery.gen_rst.save_thumbnail