# 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 | Path, gallery_conf: dict[str, Any])

  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 or Path) – 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]

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

  remove_config_comments(code_block: str) → str

    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

    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 | Path, return_node: bool = False) → tuple[dict, list[Block], None]

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

    Parameters:

      - source_file (str or Path) – 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.