Doc

Utilities for parsing and formatting documentation.

final class yuio.doc.Formatter(ctx: ReprContext, *, allow_headings: bool = True)

A formatter suitable for displaying RST/Markdown documents in the terminal.

Parameters:

• ctx – a ReprContext that’s used to colorize or wrap rendered document.

• allow_headings – if set to False, headings are rendered as paragraphs.

format(

node: AstBase,

/,

) → list[ColorizedString]

Format a parsed document.

Parameters:

node – AST node to format.

Returns:

rendered document as a list of individual lines without newline characters at the end.

class yuio.doc.DocParser

Base class for document parsers.

abstractmethod parse(s: str, /) → Document

Parse the given document and return its AST structure.

Parameters:

s – document to parse.

Returns:

document AST.

abstractmethod parse_paragraph(s: str, /) → list[str | TextRegion]

Parse inline markup in the given paragraph.

Parameters:

s – paragraph to parse.

Returns:

inline AST.

AST

class yuio.doc.AstBase

Base class for all AST nodes that represent parsed Markdown and RST documents.

dump(indent: str = '') → str

Dump an AST node into a lisp-like text representation.

class yuio.doc.Raw(*, raw: ColorizedString)

Embeds already formatted paragraph into the document.

raw: ColorizedString

Raw colorized string to add to the document.

class yuio.doc.Text(*, items: list[str | TextRegion])

Base class for all text-based AST nodes, i.e. paragraphs, headings, etc.

items: list[str | TextRegion]

Text lines as parsed from the original document.

class yuio.doc.TextRegion(*args: str | TextRegion)

Text region with special formatting.

content: list[str | TextRegion]

Region contents.

class yuio.doc.Container(*, items: list[TAst])

Base class for all container-based AST nodes, i.e. list items or quotes.

This class works as a list of items. Usually it contains arbitrary AST nodes, but it can also be limited to specific kinds of nodes via its generic variable.

items: list[TAst]

Inner AST nodes in the container.

class yuio.doc.Document(*, items: list[TAst])

Root node that contains the entire document.

class yuio.doc.ThematicBreak

Represents a visual break in text, a.k.a. an asterism.

class yuio.doc.Heading(*, items: list[str | TextRegion], level: int)

Represents a heading.

level: int

Level of the heading, 1-based.

class yuio.doc.Paragraph(*, items: list[str | TextRegion])

Represents a regular paragraph.

class yuio.doc.Quote(*, items: list[TAst])

Represents a quotation block.

class yuio.doc.Admonition(

*,

items: list[TAst],

title: list[str | TextRegion],

type: str,

)

Represents an admonition block.

title: list[str | TextRegion]

Main title.

type: str

Admonition type.

class yuio.doc.Footnote(*, items: list[TAst], marker: str)

Represents a footnote.

marker: str

Footnote number or marker.

class yuio.doc.FootnoteContainer(*, items: list[TAst])

Container for footnotes, enables compact rendering.

class yuio.doc.Code(*, lines: list[str], syntax: str)

Represents a highlighted block of code.

lines: list[str]

Code lines as parsed from the original document.

syntax: str

Syntax indicator as parsed form the original document.

class yuio.doc.ListEnumeratorKind(*values)

For enumerated lists, represents how numbers should look.

NUMBER = 'NUMBER'

Numeric, i.e. 1, 2, 3.

SMALL_LETTER = 'SMALL_LETTER'

Small letters, i.e. a, b, c.

CAPITAL_LETTER = 'CAPITAL_LETTER'

Capital letters, i.e. A, B, C.

SMALL_ROMAN = 'SMALL_ROMAN'

Small roman numerals, i.e. i, ii, iii.

CAPITAL_ROMAN = 'CAPITAL_ROMAN'

Capital roman numerals, i.e. I, II, III.

class yuio.doc.ListMarkerKind(*values)

For enumerated lists, represents how numbers are stylized.

DOT = 'DOT'

Dot after a number, i.e. 1..

PAREN = 'PAREN'

Paren after a number, i.e. 1).

ENCLOSED = 'ENCLOSED'

Parens around a number, i.e. (1).

class yuio.doc.ListItem(*, items: list[TAst], number: int | None)

A possibly numbered element of a list.

number: int | None

If present, this is the item’s number in a numbered list.

class yuio.doc.List(

*,

items: list[TAst],

enumerator_kind: ListEnumeratorKind | str | None = None,

marker_kind: ListMarkerKind | None = None,

)

A collection of list items.

enumerator_kind: ListEnumeratorKind | str | None

Enumerator kind for numbered lists, or symbol for bullet lists.

marker_kind: ListMarkerKind | None

Marker kind for numbered lists.

class yuio.doc.NoHeadings(*, items: list[TAst])

Suppresses headings rendering for its children.

class yuio.doc.Cut

Stops rendering of the container.

Helpers

yuio.doc.to_roman(n: int, /) → str

Convert positive integer to lower-case roman numeral.

yuio.doc.from_roman(s: str, /) → int | None

Parse roman numeral, return None if parsing fails.

yuio.doc.to_letters(n: int, /) → str

Convert positive integer to lowercase excel-column-like letter numeral.

yuio.doc.from_letters(s: str, /)

Parse excel-column-like letter numeral, return None if parsing fails.