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)[source]¶ Return reStructuredText code block from code string
-
sphinx_gallery.gen_rst.
executable_script
(src_file, gallery_conf)[source]¶ Validate if script has to be run according to gallery configuration
Parameters: Returns: True if script has to be executed
Return type:
-
sphinx_gallery.gen_rst.
execute_code_block
(compiler, block, example_globals, script_vars, gallery_conf)[source]¶ Executes the code block of the example file
-
sphinx_gallery.gen_rst.
execute_script
(script_blocks, script_vars, gallery_conf)[source]¶ 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)[source]¶ Extract and clean the first paragraph of module-level docstring.
-
sphinx_gallery.gen_rst.
generate_dir_rst
(src_dir, target_dir, gallery_conf, seen_backrefs)[source]¶ Generate the gallery reStructuredText for an example directory.
-
sphinx_gallery.gen_rst.
generate_file_rst
(fname, target_dir, src_dir, gallery_conf, seen_backrefs=None)[source]¶ 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.
-
sphinx_gallery.gen_rst.
md5sum_is_current
(src_file)[source]¶ Checks whether src_file has the same md5 hash as the one on disk
-
sphinx_gallery.gen_rst.
patch_warnings
()[source]¶ Patch warnings.showwarning to actually write out the warning.
-
sphinx_gallery.gen_rst.
rst_blocks
(script_blocks, output_blocks, file_conf, gallery_conf)[source]¶ 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:
-
sphinx_gallery.gen_rst.
save_rst_example
(example_rst, example_file, time_elapsed, memory_used, gallery_conf)[source]¶ 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