| """Custom docutils writer for plain text.""" |
| from __future__ import annotations |
| |
| import math |
| import os |
| import re |
| import textwrap |
| from collections.abc import Generator, Iterable, Sequence |
| from itertools import chain, groupby |
| from typing import TYPE_CHECKING, Any, cast |
| |
| from docutils import nodes, writers |
| from docutils.utils import column_width |
| |
| from sphinx import addnodes |
| from sphinx.locale import _, admonitionlabels |
| from sphinx.util.docutils import SphinxTranslator |
| |
| if TYPE_CHECKING: |
| from docutils.nodes import Element, Text |
| |
| from sphinx.builders.text import TextBuilder |
| |
| |
| class Cell: |
| """Represents a cell in a table. |
| It can span multiple columns or multiple lines. |
| """ |
| def __init__(self, text: str = "", rowspan: int = 1, colspan: int = 1) -> None: |
| self.text = text |
| self.wrapped: list[str] = [] |
| self.rowspan = rowspan |
| self.colspan = colspan |
| self.col: int | None = None |
| self.row: int | None = None |
| |
| def __repr__(self) -> str: |
| return f"<Cell {self.text!r} {self.row}v{self.rowspan}/{self.col}>{self.colspan}>" |
| |
| def __hash__(self) -> int: |
| return hash((self.col, self.row)) |
| |
| def __bool__(self) -> bool: |
| return self.text != '' and self.col is not None and self.row is not None |
| |
| def wrap(self, width: int) -> None: |
| self.wrapped = my_wrap(self.text, width) |
| |
| |
| class Table: |
| """Represents a table, handling cells that can span multiple lines |
| or rows, like:: |
| |
| +-----------+-----+ |
| | AAA | BBB | |
| +-----+-----+ | |
| | | XXX | | |
| | +-----+-----+ |
| | DDD | CCC | |
| +-----+-----------+ |
| |
| This class can be used in two ways, either: |
| |
| - With absolute positions: call ``table[line, col] = Cell(...)``, |
| this overwrites any existing cell(s) at these positions. |
| |
| - With relative positions: call the ``add_row()`` and |
| ``add_cell(Cell(...))`` as needed. |
| |
| Cells spanning multiple rows or multiple columns (having a |
| colspan or rowspan greater than one) are automatically referenced |
| by all the table cells they cover. This is a useful |
| representation as we can simply check |
| ``if self[x, y] is self[x, y+1]`` to recognize a rowspan. |
| |
| Colwidth is not automatically computed, it has to be given, either |
| at construction time, or during the table construction. |
| |
| Example usage:: |
| |
| table = Table([6, 6]) |
| table.add_cell(Cell("foo")) |
| table.add_cell(Cell("bar")) |
| table.set_separator() |
| table.add_row() |
| table.add_cell(Cell("FOO")) |
| table.add_cell(Cell("BAR")) |
| print(table) |
| +--------+--------+ |
| | foo | bar | |
| |========|========| |
| | FOO | BAR | |
| +--------+--------+ |
| |
| """ |
| def __init__(self, colwidth: list[int] | None = None) -> None: |
| self.lines: list[list[Cell]] = [] |
| self.separator = 0 |
| self.colwidth: list[int] = (colwidth if colwidth is not None else []) |
| self.current_line = 0 |
| self.current_col = 0 |
| |
| def add_row(self) -> None: |
| """Add a row to the table, to use with ``add_cell()``. It is not needed |
| to call ``add_row()`` before the first ``add_cell()``. |
| """ |
| self.current_line += 1 |
| self.current_col = 0 |
| |
| def set_separator(self) -> None: |
| """Sets the separator below the current line.""" |
| self.separator = len(self.lines) |
| |
| def add_cell(self, cell: Cell) -> None: |
| """Add a cell to the current line, to use with ``add_row()``. To add |
| a cell spanning multiple lines or rows, simply set the |
| ``cell.colspan`` or ``cell.rowspan`` BEFORE inserting it into |
| the table. |
| """ |
| while self[self.current_line, self.current_col]: |
| self.current_col += 1 |
| self[self.current_line, self.current_col] = cell |
| self.current_col += cell.colspan |
| |
| def __getitem__(self, pos: tuple[int, int]) -> Cell: |
| line, col = pos |
| self._ensure_has_line(line + 1) |
| self._ensure_has_column(col + 1) |
| return self.lines[line][col] |
| |
| def __setitem__(self, pos: tuple[int, int], cell: Cell) -> None: |
| line, col = pos |
| self._ensure_has_line(line + cell.rowspan) |
| self._ensure_has_column(col + cell.colspan) |
| for dline in range(cell.rowspan): |
| for dcol in range(cell.colspan): |
| self.lines[line + dline][col + dcol] = cell |
| cell.row = line |
| cell.col = col |
| |
| def _ensure_has_line(self, line: int) -> None: |
| while len(self.lines) < line: |
| self.lines.append([]) |
| |
| def _ensure_has_column(self, col: int) -> None: |
| for line in self.lines: |
| while len(line) < col: |
| line.append(Cell()) |
| |
| def __repr__(self) -> str: |
| return "\n".join(repr(line) for line in self.lines) |
| |
| def cell_width(self, cell: Cell, source: list[int]) -> int: |
| """Give the cell width, according to the given source (either |
| ``self.colwidth`` or ``self.measured_widths``). |
| This takes into account cells spanning multiple columns. |
| """ |
| if cell.row is None or cell.col is None: |
| msg = 'Cell co-ordinates have not been set' |
| raise ValueError(msg) |
| width = 0 |
| for i in range(self[cell.row, cell.col].colspan): |
| width += source[cell.col + i] |
| return width + (cell.colspan - 1) * 3 |
| |
| @property |
| def cells(self) -> Generator[Cell, None, None]: |
| seen: set[Cell] = set() |
| for line in self.lines: |
| for cell in line: |
| if cell and cell not in seen: |
| yield cell |
| seen.add(cell) |
| |
| def rewrap(self) -> None: |
| """Call ``cell.wrap()`` on all cells, and measure each column width |
| after wrapping (result written in ``self.measured_widths``). |
| """ |
| self.measured_widths = self.colwidth[:] |
| for cell in self.cells: |
| cell.wrap(width=self.cell_width(cell, self.colwidth)) |
| if not cell.wrapped: |
| continue |
| if cell.row is None or cell.col is None: |
| msg = 'Cell co-ordinates have not been set' |
| raise ValueError(msg) |
| width = math.ceil(max(column_width(x) for x in cell.wrapped) / cell.colspan) |
| for col in range(cell.col, cell.col + cell.colspan): |
| self.measured_widths[col] = max(self.measured_widths[col], width) |
| |
| def physical_lines_for_line(self, line: list[Cell]) -> int: |
| """For a given line, compute the number of physical lines it spans |
| due to text wrapping. |
| """ |
| physical_lines = 1 |
| for cell in line: |
| physical_lines = max(physical_lines, len(cell.wrapped)) |
| return physical_lines |
| |
| def __str__(self) -> str: |
| out = [] |
| self.rewrap() |
| |
| def writesep(char: str = "-", lineno: int | None = None) -> str: |
| """Called on the line *before* lineno. |
| Called with no *lineno* for the last sep. |
| """ |
| out: list[str] = [] |
| for colno, width in enumerate(self.measured_widths): |
| if ( |
| lineno is not None and |
| lineno > 0 and |
| self[lineno, colno] is self[lineno - 1, colno] |
| ): |
| out.append(" " * (width + 2)) |
| else: |
| out.append(char * (width + 2)) |
| head = "+" if out[0][0] == "-" else "|" |
| tail = "+" if out[-1][0] == "-" else "|" |
| glue = [ |
| "+" if left[0] == "-" or right[0] == "-" else "|" |
| for left, right in zip(out, out[1:]) |
| ] |
| glue.append(tail) |
| return head + "".join(chain.from_iterable(zip(out, glue))) |
| |
| for lineno, line in enumerate(self.lines): |
| if self.separator and lineno == self.separator: |
| out.append(writesep("=", lineno)) |
| else: |
| out.append(writesep("-", lineno)) |
| for physical_line in range(self.physical_lines_for_line(line)): |
| linestr = ["|"] |
| for colno, cell in enumerate(line): |
| if cell.col != colno: |
| continue |
| if lineno != cell.row: # NoQA: SIM114 |
| physical_text = "" |
| elif physical_line >= len(cell.wrapped): |
| physical_text = "" |
| else: |
| physical_text = cell.wrapped[physical_line] |
| adjust_len = len(physical_text) - column_width(physical_text) |
| linestr.append( |
| " " + |
| physical_text.ljust( |
| self.cell_width(cell, self.measured_widths) + 1 + adjust_len, |
| ) + "|", |
| ) |
| out.append("".join(linestr)) |
| out.append(writesep("-")) |
| return "\n".join(out) |
| |
| |
| class TextWrapper(textwrap.TextWrapper): |
| """Custom subclass that uses a different word separator regex.""" |
| |
| wordsep_re = re.compile( |
| r'(\s+|' # any whitespace |
| r'(?<=\s)(?::[a-z-]+:)?`\S+|' # interpreted text start |
| r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|' # hyphenated words |
| r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash |
| |
| def _wrap_chunks(self, chunks: list[str]) -> list[str]: |
| """_wrap_chunks(chunks : [string]) -> [string] |
| |
| The original _wrap_chunks uses len() to calculate width. |
| This method respects wide/fullwidth characters for width adjustment. |
| """ |
| lines: list[str] = [] |
| if self.width <= 0: |
| raise ValueError("invalid width %r (must be > 0)" % self.width) |
| |
| chunks.reverse() |
| |
| while chunks: |
| cur_line = [] |
| cur_len = 0 |
| |
| if lines: |
| indent = self.subsequent_indent |
| else: |
| indent = self.initial_indent |
| |
| width = self.width - column_width(indent) |
| |
| if self.drop_whitespace and chunks[-1].strip() == '' and lines: |
| del chunks[-1] |
| |
| while chunks: |
| l = column_width(chunks[-1]) |
| |
| if cur_len + l <= width: |
| cur_line.append(chunks.pop()) |
| cur_len += l |
| |
| else: |
| break |
| |
| if chunks and column_width(chunks[-1]) > width: |
| self._handle_long_word(chunks, cur_line, cur_len, width) |
| |
| if self.drop_whitespace and cur_line and cur_line[-1].strip() == '': |
| del cur_line[-1] |
| |
| if cur_line: |
| lines.append(indent + ''.join(cur_line)) |
| |
| return lines |
| |
| def _break_word(self, word: str, space_left: int) -> tuple[str, str]: |
| """_break_word(word : string, space_left : int) -> (string, string) |
| |
| Break line by unicode width instead of len(word). |
| """ |
| total = 0 |
| for i, c in enumerate(word): |
| total += column_width(c) |
| if total > space_left: |
| return word[:i - 1], word[i - 1:] |
| return word, '' |
| |
| def _split(self, text: str) -> list[str]: |
| """_split(text : string) -> [string] |
| |
| Override original method that only split by 'wordsep_re'. |
| This '_split' splits wide-characters into chunks by one character. |
| """ |
| def split(t: str) -> list[str]: |
| return super(TextWrapper, self)._split(t) |
| chunks: list[str] = [] |
| for chunk in split(text): |
| for w, g in groupby(chunk, column_width): |
| if w == 1: |
| chunks.extend(split(''.join(g))) |
| else: |
| chunks.extend(list(g)) |
| return chunks |
| |
| def _handle_long_word(self, reversed_chunks: list[str], cur_line: list[str], |
| cur_len: int, width: int) -> None: |
| """_handle_long_word(chunks : [string], |
| cur_line : [string], |
| cur_len : int, width : int) |
| |
| Override original method for using self._break_word() instead of slice. |
| """ |
| space_left = max(width - cur_len, 1) |
| if self.break_long_words: |
| l, r = self._break_word(reversed_chunks[-1], space_left) |
| cur_line.append(l) |
| reversed_chunks[-1] = r |
| |
| elif not cur_line: |
| cur_line.append(reversed_chunks.pop()) |
| |
| |
| MAXWIDTH = 70 |
| STDINDENT = 3 |
| |
| |
| def my_wrap(text: str, width: int = MAXWIDTH, **kwargs: Any) -> list[str]: |
| w = TextWrapper(width=width, **kwargs) |
| return w.wrap(text) |
| |
| |
| class TextWriter(writers.Writer): |
| supported = ('text',) |
| settings_spec = ('No options here.', '', ()) |
| settings_defaults: dict[str, Any] = {} |
| |
| output: str |
| |
| def __init__(self, builder: TextBuilder) -> None: |
| super().__init__() |
| self.builder = builder |
| |
| def translate(self) -> None: |
| visitor = self.builder.create_translator(self.document, self.builder) |
| self.document.walkabout(visitor) |
| self.output = cast(TextTranslator, visitor).body |
| |
| |
| class TextTranslator(SphinxTranslator): |
| builder: TextBuilder |
| |
| def __init__(self, document: nodes.document, builder: TextBuilder) -> None: |
| super().__init__(document, builder) |
| |
| newlines = self.config.text_newlines |
| if newlines == 'windows': |
| self.nl = '\r\n' |
| elif newlines == 'native': |
| self.nl = os.linesep |
| else: |
| self.nl = '\n' |
| self.sectionchars = self.config.text_sectionchars |
| self.add_secnumbers = self.config.text_add_secnumbers |
| self.secnumber_suffix = self.config.text_secnumber_suffix |
| self.states: list[list[tuple[int, str | list[str]]]] = [[]] |
| self.stateindent = [0] |
| self.list_counter: list[int] = [] |
| self.sectionlevel = 0 |
| self.lineblocklevel = 0 |
| self.table: Table |
| |
| self.context: list[str] = [] |
| """Heterogeneous stack. |
| |
| Used by visit_* and depart_* functions in conjunction with the tree |
| traversal. Make sure that the pops correspond to the pushes. |
| """ |
| |
| def add_text(self, text: str) -> None: |
| self.states[-1].append((-1, text)) |
| |
| def new_state(self, indent: int = STDINDENT) -> None: |
| self.states.append([]) |
| self.stateindent.append(indent) |
| |
| def end_state( |
| self, wrap: bool = True, end: Sequence[str] | None = ('',), first: str | None = None, |
| ) -> None: |
| content = self.states.pop() |
| maxindent = sum(self.stateindent) |
| indent = self.stateindent.pop() |
| result: list[tuple[int, list[str]]] = [] |
| toformat: list[str] = [] |
| |
| def do_format() -> None: |
| if not toformat: |
| return |
| if wrap: |
| res = my_wrap(''.join(toformat), width=MAXWIDTH - maxindent) |
| else: |
| res = ''.join(toformat).splitlines() |
| if end: |
| res += end |
| result.append((indent, res)) |
| for itemindent, item in content: |
| if itemindent == -1: |
| toformat.append(item) # type: ignore[arg-type] |
| else: |
| do_format() |
| result.append((indent + itemindent, item)) # type: ignore[arg-type] |
| toformat = [] |
| do_format() |
| if first is not None and result: |
| # insert prefix into first line (ex. *, [1], See also, etc.) |
| newindent = result[0][0] - indent |
| if result[0][1] == ['']: |
| result.insert(0, (newindent, [first])) |
| else: |
| text = first + result[0][1].pop(0) |
| result.insert(0, (newindent, [text])) |
| |
| self.states[-1].extend(result) |
| |
| def visit_document(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_document(self, node: Element) -> None: |
| self.end_state() |
| self.body = self.nl.join(line and (' ' * indent + line) |
| for indent, lines in self.states[0] |
| for line in lines) |
| # XXX header/footer? |
| |
| def visit_section(self, node: Element) -> None: |
| self._title_char = self.sectionchars[self.sectionlevel] |
| self.sectionlevel += 1 |
| |
| def depart_section(self, node: Element) -> None: |
| self.sectionlevel -= 1 |
| |
| def visit_topic(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_topic(self, node: Element) -> None: |
| self.end_state() |
| |
| visit_sidebar = visit_topic |
| depart_sidebar = depart_topic |
| |
| def visit_rubric(self, node: Element) -> None: |
| self.new_state(0) |
| self.add_text('-[ ') |
| |
| def depart_rubric(self, node: Element) -> None: |
| self.add_text(' ]-') |
| self.end_state() |
| |
| def visit_compound(self, node: Element) -> None: |
| pass |
| |
| def depart_compound(self, node: Element) -> None: |
| pass |
| |
| def visit_glossary(self, node: Element) -> None: |
| pass |
| |
| def depart_glossary(self, node: Element) -> None: |
| pass |
| |
| def visit_title(self, node: Element) -> None: |
| if isinstance(node.parent, nodes.Admonition): |
| self.add_text(node.astext() + ': ') |
| raise nodes.SkipNode |
| self.new_state(0) |
| |
| def get_section_number_string(self, node: Element) -> str: |
| if isinstance(node.parent, nodes.section): |
| anchorname = '#' + node.parent['ids'][0] |
| numbers = self.builder.secnumbers.get(anchorname) |
| if numbers is None: |
| numbers = self.builder.secnumbers.get('') |
| if numbers is not None: |
| return '.'.join(map(str, numbers)) + self.secnumber_suffix |
| return '' |
| |
| def depart_title(self, node: Element) -> None: |
| if isinstance(node.parent, nodes.section): |
| char = self._title_char |
| else: |
| char = '^' |
| text = '' |
| text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) # type: ignore[misc] |
| if self.add_secnumbers: |
| text = self.get_section_number_string(node) + text |
| self.stateindent.pop() |
| title = ['', text, '%s' % (char * column_width(text)), ''] |
| if len(self.states) == 2 and len(self.states[-1]) == 0: |
| # remove an empty line before title if it is first section title in the document |
| title.pop(0) |
| self.states[-1].append((0, title)) |
| |
| def visit_subtitle(self, node: Element) -> None: |
| pass |
| |
| def depart_subtitle(self, node: Element) -> None: |
| pass |
| |
| def visit_attribution(self, node: Element) -> None: |
| self.add_text('-- ') |
| |
| def depart_attribution(self, node: Element) -> None: |
| pass |
| |
| ############################################################# |
| # Domain-specific object descriptions |
| ############################################################# |
| |
| # Top-level nodes |
| ################# |
| |
| def visit_desc(self, node: Element) -> None: |
| pass |
| |
| def depart_desc(self, node: Element) -> None: |
| pass |
| |
| def visit_desc_signature(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_desc_signature(self, node: Element) -> None: |
| # XXX: wrap signatures in a way that makes sense |
| self.end_state(wrap=False, end=None) |
| |
| def visit_desc_signature_line(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_signature_line(self, node: Element) -> None: |
| self.add_text('\n') |
| |
| def visit_desc_content(self, node: Element) -> None: |
| self.new_state() |
| self.add_text(self.nl) |
| |
| def depart_desc_content(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_desc_inline(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_inline(self, node: Element) -> None: |
| pass |
| |
| # Nodes for high-level structure in signatures |
| ############################################## |
| |
| def visit_desc_name(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_name(self, node: Element) -> None: |
| pass |
| |
| def visit_desc_addname(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_addname(self, node: Element) -> None: |
| pass |
| |
| def visit_desc_type(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_type(self, node: Element) -> None: |
| pass |
| |
| def visit_desc_returns(self, node: Element) -> None: |
| self.add_text(' -> ') |
| |
| def depart_desc_returns(self, node: Element) -> None: |
| pass |
| |
| def _visit_sig_parameter_list( |
| self, |
| node: Element, |
| parameter_group: type[Element], |
| sig_open_paren: str, |
| sig_close_paren: str, |
| ) -> None: |
| """Visit a signature parameters or type parameters list. |
| |
| The *parameter_group* value is the type of a child node acting as a required parameter |
| or as a set of contiguous optional parameters. |
| """ |
| self.add_text(sig_open_paren) |
| self.is_first_param = True |
| self.optional_param_level = 0 |
| self.params_left_at_level = 0 |
| self.param_group_index = 0 |
| # Counts as what we call a parameter group are either a required parameter, or a |
| # set of contiguous optional ones. |
| self.list_is_required_param = [isinstance(c, parameter_group) for c in node.children] |
| self.required_params_left = sum(self.list_is_required_param) |
| self.param_separator = ', ' |
| self.multi_line_parameter_list = node.get('multi_line_parameter_list', False) |
| if self.multi_line_parameter_list: |
| self.param_separator = self.param_separator.rstrip() |
| self.context.append(sig_close_paren) |
| |
| def _depart_sig_parameter_list(self, node: Element) -> None: |
| sig_close_paren = self.context.pop() |
| self.add_text(sig_close_paren) |
| |
| def visit_desc_parameterlist(self, node: Element) -> None: |
| self._visit_sig_parameter_list(node, addnodes.desc_parameter, '(', ')') |
| |
| def depart_desc_parameterlist(self, node: Element) -> None: |
| self._depart_sig_parameter_list(node) |
| |
| def visit_desc_type_parameter_list(self, node: Element) -> None: |
| self._visit_sig_parameter_list(node, addnodes.desc_type_parameter, '[', ']') |
| |
| def depart_desc_type_parameter_list(self, node: Element) -> None: |
| self._depart_sig_parameter_list(node) |
| |
| def visit_desc_parameter(self, node: Element) -> None: |
| on_separate_line = self.multi_line_parameter_list |
| if on_separate_line and not (self.is_first_param and self.optional_param_level > 0): |
| self.new_state() |
| if self.is_first_param: |
| self.is_first_param = False |
| elif not on_separate_line and not self.required_params_left: |
| self.add_text(self.param_separator) |
| if self.optional_param_level == 0: |
| self.required_params_left -= 1 |
| else: |
| self.params_left_at_level -= 1 |
| |
| self.add_text(node.astext()) |
| |
| is_required = self.list_is_required_param[self.param_group_index] |
| if on_separate_line: |
| is_last_group = self.param_group_index + 1 == len(self.list_is_required_param) |
| next_is_required = ( |
| not is_last_group |
| and self.list_is_required_param[self.param_group_index + 1] |
| ) |
| opt_param_left_at_level = self.params_left_at_level > 0 |
| if opt_param_left_at_level or is_required and (is_last_group or next_is_required): |
| self.add_text(self.param_separator) |
| self.end_state(wrap=False, end=None) |
| |
| elif self.required_params_left: |
| self.add_text(self.param_separator) |
| |
| if is_required: |
| self.param_group_index += 1 |
| raise nodes.SkipNode |
| |
| def visit_desc_type_parameter(self, node: Element) -> None: |
| self.visit_desc_parameter(node) |
| |
| def visit_desc_optional(self, node: Element) -> None: |
| self.params_left_at_level = sum([isinstance(c, addnodes.desc_parameter) |
| for c in node.children]) |
| self.optional_param_level += 1 |
| self.max_optional_param_level = self.optional_param_level |
| if self.multi_line_parameter_list: |
| # If the first parameter is optional, start a new line and open the bracket. |
| if self.is_first_param: |
| self.new_state() |
| self.add_text('[') |
| # Else, if there remains at least one required parameter, append the |
| # parameter separator, open a new bracket, and end the line. |
| elif self.required_params_left: |
| self.add_text(self.param_separator) |
| self.add_text('[') |
| self.end_state(wrap=False, end=None) |
| # Else, open a new bracket, append the parameter separator, and end the |
| # line. |
| else: |
| self.add_text('[') |
| self.add_text(self.param_separator) |
| self.end_state(wrap=False, end=None) |
| else: |
| self.add_text('[') |
| |
| def depart_desc_optional(self, node: Element) -> None: |
| self.optional_param_level -= 1 |
| if self.multi_line_parameter_list: |
| # If it's the first time we go down one level, add the separator before the |
| # bracket. |
| if self.optional_param_level == self.max_optional_param_level - 1: |
| self.add_text(self.param_separator) |
| self.add_text(']') |
| # End the line if we have just closed the last bracket of this group of |
| # optional parameters. |
| if self.optional_param_level == 0: |
| self.end_state(wrap=False, end=None) |
| |
| else: |
| self.add_text(']') |
| if self.optional_param_level == 0: |
| self.param_group_index += 1 |
| |
| def visit_desc_annotation(self, node: Element) -> None: |
| pass |
| |
| def depart_desc_annotation(self, node: Element) -> None: |
| pass |
| |
| ############################################## |
| |
| def visit_figure(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_figure(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_caption(self, node: Element) -> None: |
| pass |
| |
| def depart_caption(self, node: Element) -> None: |
| pass |
| |
| def visit_productionlist(self, node: Element) -> None: |
| self.new_state() |
| names = [] |
| productionlist = cast(Iterable[addnodes.production], node) |
| for production in productionlist: |
| names.append(production['tokenname']) |
| maxlen = max(len(name) for name in names) |
| lastname = None |
| for production in productionlist: |
| if production['tokenname']: |
| self.add_text(production['tokenname'].ljust(maxlen) + ' ::=') |
| lastname = production['tokenname'] |
| elif lastname is not None: |
| self.add_text('%s ' % (' ' * len(lastname))) |
| self.add_text(production.astext() + self.nl) |
| self.end_state(wrap=False) |
| raise nodes.SkipNode |
| |
| def visit_footnote(self, node: Element) -> None: |
| label = cast(nodes.label, node[0]) |
| self._footnote = label.astext().strip() |
| self.new_state(len(self._footnote) + 3) |
| |
| def depart_footnote(self, node: Element) -> None: |
| self.end_state(first='[%s] ' % self._footnote) |
| |
| def visit_citation(self, node: Element) -> None: |
| if len(node) and isinstance(node[0], nodes.label): |
| self._citlabel = node[0].astext() |
| else: |
| self._citlabel = '' |
| self.new_state(len(self._citlabel) + 3) |
| |
| def depart_citation(self, node: Element) -> None: |
| self.end_state(first='[%s] ' % self._citlabel) |
| |
| def visit_label(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_legend(self, node: Element) -> None: |
| pass |
| |
| def depart_legend(self, node: Element) -> None: |
| pass |
| |
| # XXX: option list could use some better styling |
| |
| def visit_option_list(self, node: Element) -> None: |
| pass |
| |
| def depart_option_list(self, node: Element) -> None: |
| pass |
| |
| def visit_option_list_item(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_option_list_item(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_option_group(self, node: Element) -> None: |
| self._firstoption = True |
| |
| def depart_option_group(self, node: Element) -> None: |
| self.add_text(' ') |
| |
| def visit_option(self, node: Element) -> None: |
| if self._firstoption: |
| self._firstoption = False |
| else: |
| self.add_text(', ') |
| |
| def depart_option(self, node: Element) -> None: |
| pass |
| |
| def visit_option_string(self, node: Element) -> None: |
| pass |
| |
| def depart_option_string(self, node: Element) -> None: |
| pass |
| |
| def visit_option_argument(self, node: Element) -> None: |
| self.add_text(node['delimiter']) |
| |
| def depart_option_argument(self, node: Element) -> None: |
| pass |
| |
| def visit_description(self, node: Element) -> None: |
| pass |
| |
| def depart_description(self, node: Element) -> None: |
| pass |
| |
| def visit_tabular_col_spec(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_colspec(self, node: Element) -> None: |
| self.table.colwidth.append(node["colwidth"]) |
| raise nodes.SkipNode |
| |
| def visit_tgroup(self, node: Element) -> None: |
| pass |
| |
| def depart_tgroup(self, node: Element) -> None: |
| pass |
| |
| def visit_thead(self, node: Element) -> None: |
| pass |
| |
| def depart_thead(self, node: Element) -> None: |
| pass |
| |
| def visit_tbody(self, node: Element) -> None: |
| self.table.set_separator() |
| |
| def depart_tbody(self, node: Element) -> None: |
| pass |
| |
| def visit_row(self, node: Element) -> None: |
| if self.table.lines: |
| self.table.add_row() |
| |
| def depart_row(self, node: Element) -> None: |
| pass |
| |
| def visit_entry(self, node: Element) -> None: |
| self.entry = Cell( |
| rowspan=node.get("morerows", 0) + 1, colspan=node.get("morecols", 0) + 1, |
| ) |
| self.new_state(0) |
| |
| def depart_entry(self, node: Element) -> None: |
| text = self.nl.join(self.nl.join(x[1]) for x in self.states.pop()) |
| self.stateindent.pop() |
| self.entry.text = text |
| self.table.add_cell(self.entry) |
| del self.entry |
| |
| def visit_table(self, node: Element) -> None: |
| if hasattr(self, 'table'): |
| msg = 'Nested tables are not supported.' |
| raise NotImplementedError(msg) |
| self.new_state(0) |
| self.table = Table() |
| |
| def depart_table(self, node: Element) -> None: |
| self.add_text(str(self.table)) |
| del self.table |
| self.end_state(wrap=False) |
| |
| def visit_acks(self, node: Element) -> None: |
| bullet_list = cast(nodes.bullet_list, node[0]) |
| list_items = cast(Iterable[nodes.list_item], bullet_list) |
| self.new_state(0) |
| self.add_text(', '.join(n.astext() for n in list_items) + '.') |
| self.end_state() |
| raise nodes.SkipNode |
| |
| def visit_image(self, node: Element) -> None: |
| if 'alt' in node.attributes: |
| self.add_text(_('[image: %s]') % node['alt']) |
| self.add_text(_('[image]')) |
| raise nodes.SkipNode |
| |
| def visit_transition(self, node: Element) -> None: |
| indent = sum(self.stateindent) |
| self.new_state(0) |
| self.add_text('=' * (MAXWIDTH - indent)) |
| self.end_state() |
| raise nodes.SkipNode |
| |
| def visit_bullet_list(self, node: Element) -> None: |
| self.list_counter.append(-1) |
| |
| def depart_bullet_list(self, node: Element) -> None: |
| self.list_counter.pop() |
| |
| def visit_enumerated_list(self, node: Element) -> None: |
| self.list_counter.append(node.get('start', 1) - 1) |
| |
| def depart_enumerated_list(self, node: Element) -> None: |
| self.list_counter.pop() |
| |
| def visit_definition_list(self, node: Element) -> None: |
| self.list_counter.append(-2) |
| |
| def depart_definition_list(self, node: Element) -> None: |
| self.list_counter.pop() |
| |
| def visit_list_item(self, node: Element) -> None: |
| if self.list_counter[-1] == -1: |
| # bullet list |
| self.new_state(2) |
| elif self.list_counter[-1] == -2: |
| # definition list |
| pass |
| else: |
| # enumerated list |
| self.list_counter[-1] += 1 |
| self.new_state(len(str(self.list_counter[-1])) + 2) |
| |
| def depart_list_item(self, node: Element) -> None: |
| if self.list_counter[-1] == -1: |
| self.end_state(first='* ') |
| elif self.list_counter[-1] == -2: |
| pass |
| else: |
| self.end_state(first='%s. ' % self.list_counter[-1]) |
| |
| def visit_definition_list_item(self, node: Element) -> None: |
| self._classifier_count_in_li = len(list(node.findall(nodes.classifier))) |
| |
| def depart_definition_list_item(self, node: Element) -> None: |
| pass |
| |
| def visit_term(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_term(self, node: Element) -> None: |
| if not self._classifier_count_in_li: |
| self.end_state(end=None) |
| |
| def visit_classifier(self, node: Element) -> None: |
| self.add_text(' : ') |
| |
| def depart_classifier(self, node: Element) -> None: |
| self._classifier_count_in_li -= 1 |
| if not self._classifier_count_in_li: |
| self.end_state(end=None) |
| |
| def visit_definition(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_definition(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_field_list(self, node: Element) -> None: |
| pass |
| |
| def depart_field_list(self, node: Element) -> None: |
| pass |
| |
| def visit_field(self, node: Element) -> None: |
| pass |
| |
| def depart_field(self, node: Element) -> None: |
| pass |
| |
| def visit_field_name(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_field_name(self, node: Element) -> None: |
| self.add_text(':') |
| self.end_state(end=None) |
| |
| def visit_field_body(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_field_body(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_centered(self, node: Element) -> None: |
| pass |
| |
| def depart_centered(self, node: Element) -> None: |
| pass |
| |
| def visit_hlist(self, node: Element) -> None: |
| pass |
| |
| def depart_hlist(self, node: Element) -> None: |
| pass |
| |
| def visit_hlistcol(self, node: Element) -> None: |
| pass |
| |
| def depart_hlistcol(self, node: Element) -> None: |
| pass |
| |
| def visit_admonition(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_admonition(self, node: Element) -> None: |
| self.end_state() |
| |
| def _visit_admonition(self, node: Element) -> None: |
| self.new_state(2) |
| |
| def _depart_admonition(self, node: Element) -> None: |
| label = admonitionlabels[node.tagname] |
| indent = sum(self.stateindent) + len(label) |
| if (len(self.states[-1]) == 1 and |
| self.states[-1][0][0] == 0 and |
| MAXWIDTH - indent >= sum(len(s) for s in self.states[-1][0][1])): |
| # short text: append text after admonition label |
| self.stateindent[-1] += len(label) |
| self.end_state(first=label + ': ') |
| else: |
| # long text: append label before the block |
| self.states[-1].insert(0, (0, [self.nl])) |
| self.end_state(first=label + ':') |
| |
| visit_attention = _visit_admonition |
| depart_attention = _depart_admonition |
| visit_caution = _visit_admonition |
| depart_caution = _depart_admonition |
| visit_danger = _visit_admonition |
| depart_danger = _depart_admonition |
| visit_error = _visit_admonition |
| depart_error = _depart_admonition |
| visit_hint = _visit_admonition |
| depart_hint = _depart_admonition |
| visit_important = _visit_admonition |
| depart_important = _depart_admonition |
| visit_note = _visit_admonition |
| depart_note = _depart_admonition |
| visit_tip = _visit_admonition |
| depart_tip = _depart_admonition |
| visit_warning = _visit_admonition |
| depart_warning = _depart_admonition |
| visit_seealso = _visit_admonition |
| depart_seealso = _depart_admonition |
| |
| def visit_versionmodified(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_versionmodified(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_literal_block(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_literal_block(self, node: Element) -> None: |
| self.end_state(wrap=False) |
| |
| def visit_doctest_block(self, node: Element) -> None: |
| self.new_state(0) |
| |
| def depart_doctest_block(self, node: Element) -> None: |
| self.end_state(wrap=False) |
| |
| def visit_line_block(self, node: Element) -> None: |
| self.new_state() |
| self.lineblocklevel += 1 |
| |
| def depart_line_block(self, node: Element) -> None: |
| self.lineblocklevel -= 1 |
| self.end_state(wrap=False, end=None) |
| if not self.lineblocklevel: |
| self.add_text('\n') |
| |
| def visit_line(self, node: Element) -> None: |
| pass |
| |
| def depart_line(self, node: Element) -> None: |
| self.add_text('\n') |
| |
| def visit_block_quote(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_block_quote(self, node: Element) -> None: |
| self.end_state() |
| |
| def visit_compact_paragraph(self, node: Element) -> None: |
| pass |
| |
| def depart_compact_paragraph(self, node: Element) -> None: |
| pass |
| |
| def visit_paragraph(self, node: Element) -> None: |
| if not isinstance(node.parent, nodes.Admonition) or \ |
| isinstance(node.parent, addnodes.seealso): |
| self.new_state(0) |
| |
| def depart_paragraph(self, node: Element) -> None: |
| if not isinstance(node.parent, nodes.Admonition) or \ |
| isinstance(node.parent, addnodes.seealso): |
| self.end_state() |
| |
| def visit_target(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_index(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_toctree(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_substitution_definition(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_pending_xref(self, node: Element) -> None: |
| pass |
| |
| def depart_pending_xref(self, node: Element) -> None: |
| pass |
| |
| def visit_reference(self, node: Element) -> None: |
| if self.add_secnumbers: |
| numbers = node.get("secnumber") |
| if numbers is not None: |
| self.add_text('.'.join(map(str, numbers)) + self.secnumber_suffix) |
| |
| def depart_reference(self, node: Element) -> None: |
| pass |
| |
| def visit_number_reference(self, node: Element) -> None: |
| text = nodes.Text(node.get('title', '#')) |
| self.visit_Text(text) |
| raise nodes.SkipNode |
| |
| def visit_download_reference(self, node: Element) -> None: |
| pass |
| |
| def depart_download_reference(self, node: Element) -> None: |
| pass |
| |
| def visit_emphasis(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def depart_emphasis(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def visit_literal_emphasis(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def depart_literal_emphasis(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def visit_strong(self, node: Element) -> None: |
| self.add_text('**') |
| |
| def depart_strong(self, node: Element) -> None: |
| self.add_text('**') |
| |
| def visit_literal_strong(self, node: Element) -> None: |
| self.add_text('**') |
| |
| def depart_literal_strong(self, node: Element) -> None: |
| self.add_text('**') |
| |
| def visit_abbreviation(self, node: Element) -> None: |
| self.add_text('') |
| |
| def depart_abbreviation(self, node: Element) -> None: |
| if node.hasattr('explanation'): |
| self.add_text(' (%s)' % node['explanation']) |
| |
| def visit_manpage(self, node: Element) -> None: |
| return self.visit_literal_emphasis(node) |
| |
| def depart_manpage(self, node: Element) -> None: |
| return self.depart_literal_emphasis(node) |
| |
| def visit_title_reference(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def depart_title_reference(self, node: Element) -> None: |
| self.add_text('*') |
| |
| def visit_literal(self, node: Element) -> None: |
| self.add_text('"') |
| |
| def depart_literal(self, node: Element) -> None: |
| self.add_text('"') |
| |
| def visit_subscript(self, node: Element) -> None: |
| self.add_text('_') |
| |
| def depart_subscript(self, node: Element) -> None: |
| pass |
| |
| def visit_superscript(self, node: Element) -> None: |
| self.add_text('^') |
| |
| def depart_superscript(self, node: Element) -> None: |
| pass |
| |
| def visit_footnote_reference(self, node: Element) -> None: |
| self.add_text('[%s]' % node.astext()) |
| raise nodes.SkipNode |
| |
| def visit_citation_reference(self, node: Element) -> None: |
| self.add_text('[%s]' % node.astext()) |
| raise nodes.SkipNode |
| |
| def visit_Text(self, node: Text) -> None: |
| self.add_text(node.astext()) |
| |
| def depart_Text(self, node: Text) -> None: |
| pass |
| |
| def visit_generated(self, node: Element) -> None: |
| pass |
| |
| def depart_generated(self, node: Element) -> None: |
| pass |
| |
| def visit_inline(self, node: Element) -> None: |
| if 'xref' in node['classes'] or 'term' in node['classes']: |
| self.add_text('*') |
| |
| def depart_inline(self, node: Element) -> None: |
| if 'xref' in node['classes'] or 'term' in node['classes']: |
| self.add_text('*') |
| |
| def visit_container(self, node: Element) -> None: |
| pass |
| |
| def depart_container(self, node: Element) -> None: |
| pass |
| |
| def visit_problematic(self, node: Element) -> None: |
| self.add_text('>>') |
| |
| def depart_problematic(self, node: Element) -> None: |
| self.add_text('<<') |
| |
| def visit_system_message(self, node: Element) -> None: |
| self.new_state(0) |
| self.add_text('<SYSTEM MESSAGE: %s>' % node.astext()) |
| self.end_state() |
| raise nodes.SkipNode |
| |
| def visit_comment(self, node: Element) -> None: |
| raise nodes.SkipNode |
| |
| def visit_meta(self, node: Element) -> None: |
| # only valid for HTML |
| raise nodes.SkipNode |
| |
| def visit_raw(self, node: Element) -> None: |
| if 'text' in node.get('format', '').split(): |
| self.new_state(0) |
| self.add_text(node.astext()) |
| self.end_state(wrap = False) |
| raise nodes.SkipNode |
| |
| def visit_math(self, node: Element) -> None: |
| pass |
| |
| def depart_math(self, node: Element) -> None: |
| pass |
| |
| def visit_math_block(self, node: Element) -> None: |
| self.new_state() |
| |
| def depart_math_block(self, node: Element) -> None: |
| self.end_state() |
