sphinx_gallery.gen_rst — Python documentation

# 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`