sphinx_gallery.gen_rst#
reST 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.
- sphinx_gallery.gen_rst.execute_code_block(compiler, block, example_globals, script_vars, gallery_conf, file_conf)[source]#
Execute the code block of the example file.
- Parameters:
compiler (codeop.Compile) β Compiler to compile AST of code block.
block (List[Tuple[str, str, int]]) β List of Tuples, each Tuple contains label (βtextβ or βcodeβ), the corresponding content string of block and the leading line number.
example_globals (Dict[str, Any]) β Global variables for examples.
script_vars (Dict[str, Any]) β Configuration and runtime variables.
gallery_conf (Dict[str, Any]) β Gallery configurations.
file_conf (Dict[str, Any]) β File-specific settings given in source file comments as:
# sphinx_gallery_<name> = <value>
.
- Returns:
code_output β Output of executing code in reST.
- Return type:
- sphinx_gallery.gen_rst.execute_script(script_blocks, script_vars, gallery_conf, file_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
file_conf (dict) β File-specific settings given in source file comments as:
# sphinx_gallery_<name> = <value>
- 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, include_toctree=True)[source]#
Generate the gallery reStructuredText for an example directory.
- Parameters:
src_dir (str,) β Path to example directory containing python files and possibly sub categories
target_dir (str,) β Path where parsed examples (rst, python files, etc) will be outputted
gallery_conf (Dict[str, Any]) β Gallery configurations.
seen_backrefs (set,) β Back references encountered when parsing this gallery will be stored in this set.
include_toctree (bool) β Whether or not toctree should be included in generated rst file. Default = True.
- Returns:
index_path (str,) β Path to index rst file presenting the current example gallery
index_content (str,) β Content which will be written to the index rst file presenting the current example gallery
costs (List[Dict]) β
- List of dicts of costs for building each element of the gallery
with keys βtβ, βmemβ, βsrc_fileβ, and βtarget_dirβ.
toctree_items (list,) β List of files included in toctree (independent of include_toctreeβs value)
- 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_elapsed, memory_used)
required to run the script.
- sphinx_gallery.gen_rst.handle_exception(exc_info, src_file, script_vars, gallery_conf)[source]#
Trim and format exception, maybe raise error, etc.
- sphinx_gallery.gen_rst.md5sum_is_current(src_file, mode='b')[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]#
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:
- 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
- sphinx_gallery.gen_rst.save_thumbnail(image_path_template, src_file, script_vars, file_conf, gallery_conf)[source]#
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
script_vars (dict) β Configuration and run time variables
file_conf (dict) β File-specific settings given in source file comments as:
# sphinx_gallery_<name> = <value>
gallery_conf (dict) β Sphinx-Gallery configuration dictionary