RstCloth

class rstcloth.rstcloth.RstCloth(stream: typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, line_width: int = 72)

RstCloth is the base class to create a ReStructuredText document programmatically.

Parameters

• stream – output stream for writing ReStructuredText content

• line_width – Maximum length of each ReStructuredText content line. In some edge cases this limit might be crossed.

abstract(*, name: str = 'Abstract', value: str, indent: int = 0) → None

address(*, name: str = 'Address', value: str, indent: int = 0) → None

admonition(*, name: str = 'admonition', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

attention(*, name: str = 'attention', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

author(*, name: str = 'Author', value: str, indent: int = 0) → None

authors(*, name: str = 'Authors', value: str, indent: int = 0) → None

static bold(string: str) → str

Returns strongly emphasised (boldface) text.

Parameters

string – the text to write into this element

Returns

bolded text

caution(*, name: str = 'caution', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

codeblock(content: Union[str, List[str]], indent: int = 0, language: Optional[str] = None) → None

Constructs literal block.

Parameters

• content – the text to write into this element

• indent – number of spaces to indent this element

• language – formal language indication for syntax highlighter

Returns

literal block

contact(*, name: str = 'Contact', value: str, indent: int = 0) → None

content(content: Union[str, List[str]], indent: int = 0) → None

Constructs paragraph’s content.

Parameters

• content – the text to write into this element

• indent – number of spaces to indent this element

copyright(*, name: str = 'Copyright', value: str, indent: int = 0) → None

danger(*, name: str = 'danger', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

property data: str

Returns ReStructuredText document content as a string.

Returns

the content of output stream

date(*, name: str = 'Date', value: str, indent: int = 0) → None

dedication(*, name: str = 'Dedication', value: str, indent: int = 0) → None

definition(name: str, text: str, indent: int = 0, bold: bool = False) → None

Constructs definition list item.

Parameters

• name – the name of the definition

• text – the text to write into this element

• indent – number of spaces to indent this element

• bold – should definition name be bolded

directive(name: str, arg: Optional[str] = None, fields: Optional[Iterable[Tuple[str, str]]] = None, content: Optional[Union[str, List[str]]] = None, indent: int = 0) → None

Constructs reStructuredText directive.

Parameters

• name – the directive itself to use

• arg – the argument to pass into the directive

• fields – fields to append as children underneath the directive

• content – the text to write into this element

• indent – number of spaces to indent this element

static emph(string: str) → str

Returns emphasised (italics) text.

Parameters

string – the text to write into this element

Returns

emphasised text

error(*, name: str = 'error', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

field(name: str, value: str, indent: int = 0) → None

Constructs a field.

Parameters

• name – the name of the field

• value – the value of the field

• indent – number of spaces to indent this element

fill(text: str, initial_indent: int = 0, subsequent_indent: int = 0) → str

Breaks text parameter into separate lines. Each line is indented accordingly to initial_indent and subsequent_indent parameters.

Parameters

• text – input string to be wrapped and indented

• initial_indent – first line indentation size

• subsequent_indent – subsequent lines indentation size

Returns

wrapped and indented text

footnote(ref: str, text: str, indent: int = 0) → None

Constructs footnote directive.

Parameters

• ref – the reference value

• text – the text to write into this element

• indent – number of spaces to indent this element

static footnote_ref(name: str) → str

Returns footnote reference.

Parameters

name – the text to write into this element

Returns

footnote reference

frame_break(heights: int) → None

Constructs frame break.

Parameters

heights – height in points

h1(text: str, *, char: str = '=', overline: bool = False, indent: int = 0) → None

h2(text: str, *, char: str = '-', overline: bool = False, indent: int = 0) → None

h3(text: str, *, char: str = '~', overline: bool = False, indent: int = 0) → None

h4(text: str, *, char: str = '+', overline: bool = False, indent: int = 0) → None

h5(text: str, *, char: str = '^', overline: bool = False, indent: int = 0) → None

h6(text: str, *, char: str = ';', overline: bool = False, indent: int = 0) → None

heading(text: str, char: str, overline: bool = False, indent: int = 0) → None

Constructs section title.

Parameters

• text – the text to write into this element

• char – the character to line the heading with

• overline – should overline be included

• indent – number of spaces to indent this element

Returns

section title

hint(*, name: str = 'hint', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

important(*, name: str = 'important', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

static inline_link(text: str, link: str) → str

Returns hyperlink reference.

Parameters

• text – the printed value of the link

• link – the url the link should goto

Returns

hyperlink reference

li(content: Union[str, List[str]], bullet: str = '-', indent: int = 0) → None

Constructs bullet list item.

Parameters

• content – the text to write into this element

• bullet – the character of the bullet

• indent – number of spaces to indent this element

newline(count: int = 1) → None

Places a newline(s) into ReStructuredText document.

Parameters

count – the number of newlines to add

note(*, name: str = 'note', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

organization(*, name: str = 'Organization', value: str, indent: int = 0) → None

page_break(template: Optional[str] = None) → None

Constructs page break.

Parameters

template – name of the next page template

static pre(string: str) → str

Returns inline literals.

Parameters

string – the text to write into this element

Returns

inline literals

ref_target(name: str, indent: int = 0) → None

Constructs hyperlink reference target.

Parameters

• name – the name of the reference target

• indent – number of spaces to indent this element

replacement(name: str, value: str, indent: int = 0) → None

Constructs replacement directive.

Parameters

• name – the name of the replacement

• value – the value for the replacement

• indent – number of spaces to indent this element

revision(*, name: str = 'Revision', value: str, indent: int = 0) → None

classmethod role(name: Union[str, List[str]], value: str, text: Optional[str] = None) → str

Returns role with optional hyperlink.

Parameters

• name – the name of the role

• value – the value of the role

• text – text after the role

Returns

role element

spacer(horizontal: int, vertical: int) → None

Constructs a spacer.

Parameters

• horizontal – horizontal size in points

• vertical – vertical size in points

status(*, name: str = 'Status', value: str, indent: int = 0) → None

table(header: List, data: Optional[List[List]], indent=0) → None

Constructs grid table.

Parameters

• header – a list of header values (strings), to use for the table

• data – a list of lists of row data (same length as the header list each)

• indent – number of spaces to indent this element

table_list(headers: Iterable, data: Optional[List[List]], widths: Optional[Union[List[int], str]] = None, width: Optional[Union[int, str]] = None, indent: int = 0) → None

Constructs list table.

Parameters

• headers – a list of header values (strings), to use for the table

• data – a list of lists of row data (same length as the header list each)

• widths – list of relative column widths or the special value “auto”

• width – forces the width of the table to the specified length or percentage of the line width

• indent – number of spaces to indent this element

table_of_contents(name: Optional[str] = None, depth: Optional[int] = None, backlinks: Optional[str] = None) → None

Constructs table of contents.

Parameters

• name – table of contents alternative title

• depth – the number of section levels that are collected in the table of contents

• backlinks – generate links from section headers back to the table of contents entries, the table of contents itself, or generate no backlinks

tip(*, name: str = 'tip', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None

title(text: str, *, char: str = '=', overline: bool = True, indent: int = 0) → None

transition_marker() → None

Constructs transition marker.

version(*, name: str = 'Version', value: str, indent: int = 0) → None

warning(*, name: str = 'warning', arg: str = None, fields: Iterable[Tuple[str, str]] = None, content: Union[str, List[str]] = None, indent: int = 0) → None