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.
check_binder_conf
(binder_conf)¶ Check to make sure that the Binder configuration is correct.
-
sphinx_gallery.gen_rst.
clean_modules
()¶ Remove “unload” seaborn from the name space
After a script is executed it can load a variety of setting that one does not want to influence in other examples in the gallery.
-
sphinx_gallery.gen_rst.
codestr2rst
(codestr, lang='python', lineno=None)¶ Return reStructuredText code block from code string
-
sphinx_gallery.gen_rst.
execute_code_block
(compiler, src_file, code_block, lineno, example_globals, block_vars, gallery_conf)¶ Executes the code block of the example file
-
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.
figure_rst
(figure_list, sources_dir)¶ Given a list of paths to figures generate the corresponding rst
Depending on whether we have one or more figures, we use a single rst call to ‘image’ or a horizontal list.
Parameters: - figure_list (list of str) – Strings are the figures’ absolute paths
- sources_dir (str) – absolute path of Sphinx documentation sources
Returns: - images_rst (str) – rst code to embed the images in the document
- fig_num (int) – number of figures saved
-
sphinx_gallery.gen_rst.
gen_binder_rst
(fname, binder_conf, gallery_conf)¶ Generate the RST + link for the Binder badge.
Parameters: - fname (str) – The path to the .py file for which a Binder badge will be generated.
- binder_conf (dict | None) –
If a dictionary it must have the following keys:
- ‘url’: The URL of the BinderHub instance that’s running a Binder
- service.
- ‘org’: The GitHub organization to which the documentation will be
- pushed.
- ‘repo’: The GitHub repository to which the documentation will be
- pushed.
- ‘branch’: The Git branch on which the documentation exists (e.g.,
- gh-pages).
- ‘dependencies’: A list of paths to dependency files that match the
- Binderspec.
Returns: rst – The reStructuredText for the Binder badge that links to this file.
Return type: str
-
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.
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.
glr_path_static
()¶ Returns path to packaged static files
-
sphinx_gallery.gen_rst.
handle_exception
(exc_info, src_file, block_vars, gallery_conf)¶
-
sphinx_gallery.gen_rst.
indent
(text, prefix, predicate=None)¶ Adds ‘prefix’ to the beginning of selected lines in ‘text’.
If ‘predicate’ is provided, ‘prefix’ will only be added to the lines where ‘predicate(line)’ is True. If ‘predicate’ is not provided, it will default to adding ‘prefix’ to all non-empty lines that do not consist solely of whitespace characters.
-
sphinx_gallery.gen_rst.
jupyter_notebook
(script_blocks)¶ Generate a Jupyter notebook file cell-by-cell
Parameters: script_blocks (list) – script execution cells
-
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.
replace_py_ipynb
(fname)¶ Replace .py extension in filename by .ipynb
-
sphinx_gallery.gen_rst.
save_figures
(image_path, fig_count, gallery_conf)¶ Save all open matplotlib figures of the example code-block
Parameters: - image_path (str) – Path where plots are saved (format string which accepts figure number)
- fig_count (int) – Previous figure number count. Figure number add from this number
- gallery_conf (dict) – Contains the configuration of Sphinx-Gallery
Returns: - images_rst (str) – rst code to embed the images in the document
- fig_num (int) – number of figures saved
-
sphinx_gallery.gen_rst.
save_notebook
(work_notebook, write_file)¶ Saves the Jupyter work_notebook to write_file
-
sphinx_gallery.gen_rst.
save_thumbnail
(image_path_template, src_file, file_conf, gallery_conf)¶ Save the thumbnail image
-
sphinx_gallery.gen_rst.
scale_image
(in_fname, out_fname, max_width, max_height)¶ Scales an image with the same aspect ratio centered in an image with a given max_width and max_height if in_fname == out_fname the image can only be scaled down
-
sphinx_gallery.gen_rst.
split_code_and_text_blocks
(source_file)¶ Return list with source file separated into code and text blocks.
Returns: - file_conf (dict) – File-specific settings given in comments as:
# sphinx_gallery_<name> = <value>
- blocks (list of (label, content)) – List where each element is a tuple with the label (‘text’ or ‘code’), and content string of block.
- file_conf (dict) – File-specific settings given in comments as:
-
sphinx_gallery.gen_rst.
time
() → floating point number¶ Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.
-
sphinx_gallery.gen_rst.
write_backreferences
(seen_backrefs, gallery_conf, target_dir, fname, snippet)¶ Writes down back reference files, which include a thumbnail list of examples using a certain module
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.
LooseVersion
(vstring=None)¶ Version numbering for anarchists and software realists. Implements the standard interface for version number classes as described above. A version number consists of a series of numbers, separated by either periods or strings of letters. When comparing version numbers, the numeric components will be compared numerically, and the alphabetic components lexically. The following are all valid version numbers, in no particular order:
1.5.1 1.5.2b2 161 3.10a 8.02 3.4j 1996.07.12 3.2.pl0 3.1.1.6 2g6 11g 0.960923 2.2beta29 1.13++ 5.5.kw 2.0b1pl0In fact, there is no such thing as an invalid version number under this scheme; the rules for comparison are simple and predictable, but may not always give the results you want (for some definition of “want”).
-
class
sphinx_gallery.gen_rst.
MixedEncodingStringIO
¶ Helper when both ASCII and unicode strings will be written
-
class
sphinx_gallery.gen_rst.
StringIO
¶ Text I/O implementation using an in-memory buffer.
The initial_value argument sets the value of object. The newline argument is like the one of TextIOWrapper’s constructor.
-
close
()¶ Close the IO object. Attempting any further operation after the object is closed will raise a ValueError.
This method has no effect if the file is already closed.
-
getvalue
()¶ Retrieve the entire contents of the object.
-
next
¶
-
read
()¶ Read at most n characters, returned as a string.
If the argument is negative or omitted, read until EOF is reached. Return an empty string at EOF.
-
readable
() → bool. Returns True if the IO object can be read.¶
-
readline
()¶ Read until newline or EOF.
Returns an empty string if EOF is hit immediately.
-
seek
()¶ Change stream position.
- Seek to character offset pos relative to position indicated by whence:
- 0 Start of stream (the default). pos should be >= 0; 1 Current position - pos must be 0; 2 End of stream - pos must be 0.
Returns the new absolute position.
-
seekable
() → bool. Returns True if the IO object can be seeked.¶
-
tell
()¶ Tell the current file position.
-
truncate
()¶ Truncate size to pos.
The pos argument defaults to the current file position, as returned by tell(). The current file position is unchanged. Returns the new absolute position.
-
writable
() → bool. Returns True if the IO object can be written.¶
-
write
()¶ Write string to file.
Returns the number of characters written, which is always equal to the length of the string.
-