Source Code

class sphinx_parsed_codeblock.sphinx_parsed_codeblock.MarkupHtmlFormatter(node: parsed_code_block, visitor: HTML5Translator, **options)

Bases: HtmlFormatter

Pygments HTML formatter that is aware of Sphinx.

A custom HTML formatter for pygments that is aware of the sphinx node it is formatting and its corresponding sphinx HTML formatter.

Parameters:

node: The sphinx node being formatted. This node should contain children nodes that carry the markup information.
visitor: The sphinx HTML formatter used for creating the sphinx HTML output.
**options: Pygments pygments.formatters.html.HtmlFormatter options.

Methods

format_unencoded(tokensource, outfile)

The formatting process uses several nested generators; which of them are used is determined by the user's options.

format_unencoded(tokensource: Generator, outfile: IO) → None

The formatting process uses several nested generators; which of them are used is determined by the user’s options.

Each generator should take at least one argument, inner, and wrap the pieces of text generated by this.

Always yield 2-tuples: (code, text). If “code” is 1, the text is part of the original tokensource being highlighted, if it’s 0, the text is some piece of wrapping. This makes it possible to use several different wrappers that process the original source linewise, e.g. line number generators.

class sphinx_parsed_codeblock.sphinx_parsed_codeblock.ParsedCodeBlock(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: CodeBlock

Methods

run

class sphinx_parsed_codeblock.sphinx_parsed_codeblock.PygmentsLineState(line: str)

Bases: object

Class for storing the current state of a Pygments line, used in MarkupHtmlFormatter.

Given one line of text formatted by Pygments HTML formatter, this line is split into each individual  element - these can be iterated over to yield consecutive elements.

Parameters:

line: One line of text formatted by Pygments HTML formatter.

Attributes:

html_span: The opening element and any other opening HTML tags.
text: The text contained in within the span tags.

Methods

`create_span`(text)	Creates a new span with `text` inside the current HTML context.
`cut`(n)	Alters the current state by cutting the first `n` elements of the text.
`iter`()	Iterates over itself while saving the current state in the process.
`next`()	Sets the state to the next element
`restore_span`()	Reconstructs the current span.

create_span(text: str) → str

Creates a new span with text inside the current HTML context.

Parameters:

text: The text to insert into current span.

Returns:

new_span: The new span with text inserted

cut(n: int) → None

Alters the current state by cutting the first n elements of the text. Also deletes the span.

Parameters:

n: The number of characters to cut.

iter() → tuple[str, str, str]: Iterates over itself while saving the current state in the process.

next() → None: Sets the state to the next element

restore_span() → str: Reconstructs the current span.

sphinx_parsed_codeblock.sphinx_parsed_codeblock.build_child_source(visitor: HTML5Translator, child: nodes.Node) → str

Formats a markup element using sphinx and returns the HTML code.

Parameters:

visitor: The node visitor used for traversing nodes and creating HTML output.
child: A child of the parsed_code_block node. Should be a child that has a markup.

Returns:

source: The HTML source for the given child.

sphinx_parsed_codeblock.sphinx_parsed_codeblock.depart_parsed_code_block(self, node: parsed_code_block) → None: Empty function; all HTML output for parsed_code_block occurs in visit_parsed_code_block

sphinx_parsed_codeblock.sphinx_parsed_codeblock.parse_complex_sphinx_source(source: str, matches: list[str]) → tuple[str, str]

Attempts to parse sphinx-formatted HTML markup to find the HTML tags responsible.

Should be used when sphinx does not format a markup element by simply enclosing the text in some HTML tags (e.g. ideally foo: **bar** -> foo: bar), but instead inserts various span elements inside, i.e. foo: **[1, 2]** -> foo: [1, 2]. In the above example, this function attempts to find and return the  and  tags.

Parameters:

source: The sphinx-formatted HTML output, with the markup present in the HTML.
matches: The text that is expected inside the tags attempted to be found. Used for logging in case of failure.

Returns:

start_tag: The start HTML tag applied by sphinx. Empty string if failed.
end_tag: The end HTML tag applied by sphinx. Empty string if failed.

class sphinx_parsed_codeblock.sphinx_parsed_codeblock.parsed_code_block(rawsource: str = '', text: str = '', *children, **attributes: Any)

Bases: literal_block

Custom node for the parsed code-block - a subclass of docutils.nodes.literal_block

Methods

protect_children()

Creates a deep copy of children in a new, otherwise unused variable.

protect_children()

Creates a deep copy of children in a new, otherwise unused variable.

This is necessary for the children not to get deleted by sphinx/docutils when parsed_code_block is wrapped in docutils.nodes.container when the caption is set.

The copy is not actually used, but its mere presence fixes the issue.

sphinx_parsed_codeblock.sphinx_parsed_codeblock.setup(app: Sphinx) → dict[str, str | bool]: The main function - sets up the extension.

sphinx_parsed_codeblock.sphinx_parsed_codeblock.split_parsed_codeblock(node: parsed_code_block) → Generator[tuple[str, str | Node], None, None]

Creates a generator that yields lines and elements from a parsed code block Sphinx node.

In other words, it loops over the contents of a parsed code block Sphinx node (node). If it encounters text, it splits it into lines, otherwise it yields the markup element.

Parameters:

node: The parsed_code_block node that is being highlighted.

Yields:

text: python:str: The simple text of an element.
markup: python:str or python:None: The HTML-formatted element.

sphinx_parsed_codeblock.sphinx_parsed_codeblock.visit_parsed_code_block(self: HTML5Translator, node: parsed_code_block) → None

Visits the parsed_code_block node and creates the HTML output.

Parameters:

self: The HTML translator.
node: The parsed_code_block node to create HTML output for