sphinx_gallery.block_parser#

BlockParser divides non .py source files into blocks of code and markup text.

Classes#

class sphinx_gallery.block_parser.BlockParser(source_file: str, gallery_conf: dict[str, Any])[source]#

A parser that breaks a source file into blocks of code and markup text.

Determines the source language and identifies comment blocks using pygments.

Parameters:

  • source_file (str) – A file name that has a suffix compatible with files that are subsequently parsed

  • gallery_conf (dict) – Contains the configuration of Sphinx-Gallery.

extract_file_config(content: str) → dict[str, Any][source]#

Pull out the file-specific config specified in the docstring.

remove_config_comments(code_block: str) → str[source]#

Return the content of code_block with in-file config comments removed.

Comment lines with the pattern sphinx_gallery_[option] = [val] after the line comment character are removed, but surrounding empty lines are preserved.

Parameters:

code_block (str) – A code segment.

remove_ignore_blocks(code_block: str) → str[source]#

Return the content of code_block with ignored areas removed.

An ignore block starts with ?? sphinx_gallery_start_ignore and ends with ?? sphinx_gallery_end_ignore where ?? is the active language’s line comment marker. These lines and anything in between them will be removed, but surrounding empty lines are preserved.

Parameters:

code_block (str) – A code segment.

split_code_and_text_blocks(source_file: str, return_node: bool = False) → tuple[dict, list[Block], None][source]#

Return list with source file separated into code and text blocks.

Parameters:

  • source_file (str) – Path to the source file.

  • return_node (bool) – Ignored; returning an ast node is not supported

Returns:

  • file_conf (dict) – File-specific settings given in source file comments as: # sphinx_gallery_<name> = <value>

  • 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.

  • node (None) – Returning an ast node is not supported.