`doc_utils` module

Various Sphinx and docutils processing functions

Module functions summary

`create_table_nodes`	Converts a table specified as header row, separator rows and data rows into docutil nodes.
`create_wavedrom_reg_nodes`
`make_lexed_vhdl_node`	Create a node that includes the specified literal text that is colorized/highlighted by Pygments for the VHDL syntax.
`make_vhdl_entity_table`	Create a table that describes the ports and generics of a VHDL entity.
`parse_comment_block`	Parse a block of ReStructuredText text into a node list, while also detecting and processing Markdown tables.
`parse_markdown_table`	Attempts to parse a block of text as a markdown table
`parse_rest`	Parse a list of lines into a list of docutil nodes.

Module functions

create_table_nodes(state, headers, separators, rows, verbose=0)

Converts a table specified as header row, separator rows and data rows into docutil nodes.

Parameters:

headers (list) – list of string describing the header row
separators (list) – list of strings describing the separator row

Returns:

List of Docutil nodes (currently a list containing a single nodes.table node)

Return type:

list

create_wavedrom_reg_nodes(rows, verbose=0)

make_lexed_vhdl_node(text, classes=['highlight', 'highlight-vhdl'], options={})

Create a node that includes the specified literal text that is colorized/highlighted by Pygments for the VHDL syntax.

Parameters:

text (str) – literal text to insert
classes (list) – list of classes to apply to the root node
options (dict) – unused

Returns:

The top node containing the highlighted text nodes, such as

Return type:

docutils.nodes.literal

make_vhdl_entity_table(generics, ports)

Create a table that describes the ports and generics of a VHDL entity.

Parameters:

generics (list) – List of Namespace objects describing the generics interface. Each dict shall contain the .names, .definition and .comments attributes.
ports (list) – Same as above, but for port interfaces.

Returns:

A Docutils table containing the specified generics and ports.

Return type:

docutils.nodes.table

Notes

The table is structured as follows:

table
    -tgroup
        -colspec
        (-thead)
        (   -row)
        (       -entry)
        -tbody
            -row
                -entry
                -entry
                -...
            -row
            -...

parse_comment_block(state, lines, class_dict={}, verbose=0)

Parse a block of ReStructuredText text into a node list, while also detecting and processing Markdown tables.

Parameters:

state – parser state to be passed to the REST parser
lines (list of str) – text to be parsed as a list of str
class_dict (dict) – classes to be applied to the REST blocks

Returns:

list of docutils nodes represting the parsed text

Return type:

list

parse_markdown_table(pos, lines)

Attempts to parse a block of text as a markdown table

Parameters:

pos (int) – Line index from which markdown table decoding should be attempted
lines (list) – list of strings containing the text to decode.

Returns:

Returns the (new_pos, docutils_table_node_list) tuple if a markdown table was found, otherwise returns None.

Return type:

tuple or None

parse_rest(state, lines, class_dict={})

Parse a list of lines into a list of docutil nodes.

Nodes are not part of a top object so sections found in the parsed text can be mede part of the parent hierarchy. User-specified classes can be applied to objects specified in class_dict.

Parameters:

state
lines (list of str) – text to be parsed
class_dict (dict) – Dict in the format {object_type:class_name,…} or {object_type:[class_name, class_name…],…} that applies the specified class_name to the objects generated by the REST parser that have the tag object_type

Returns:

docutil nodes

Return type:

list

doc_utils module

`doc_utils` module