package documentation

Miscellaneous utilities for the documentation utilities.
Module code​_analyzer Lexical analysis of formal languages (i.e. code) using Pygments.
Module error​_reporting Provisional module to handle Exceptions across Python versions.
Package math This is the Docutils (Python Documentation Utilities) "math" sub-package.
Module punctuation​_chars No module docstring; 1/5 variable, 1/1 function documented
Module roman Convert to and from Roman numerals
Module smartquotes ========================= Smart Quotes for Docutils =========================
Module urischemes No summary

From __init__.py:

Class ​Bad​Option​Data​Error Undocumented
Class ​Bad​Option​Error Undocumented
Class ​Dependency​List List of dependencies, with file recording support.
Class ​Duplicate​Option​Error Undocumented
Class ​Extension​Option​Error Undocumented
Class ​Name​Value​Error Undocumented
Class ​Reporter Info/warning/error reporter and system_message element generator.
Class ​System​Message Undocumented
Class ​System​Message​Propagation Undocumented
Function assemble​_option​_dict Return a mapping of option names to values.
Function clean​_rcs​_keywords Undocumented
Function column​_indices Indices of Unicode string text when skipping combining characters.
Function column​_width Return the column width of text.
Function decode​_path Ensure path is Unicode. Return nodes.reprunicode object.
Function escape2null Return a string with escape-backslashes converted to nulls.
Function extract​_extension​_options Return a dictionary mapping extension option names to converted values.
Function extract​_name​_value Return a list of (name, value) from a line of the form "name=value ...".
Function extract​_options Return a list of option (name, value) pairs from field names & bodies.
Function find​_combining​_chars Return indices of all combining chars in Unicode string text.
Function find​_file​_in​_dirs Search for path in the list of directories dirs.
Function get​_source​_line Return the "source" and "line" attributes from the node given or from its closest ancestor.
Function get​_stylesheet​_list Retrieve list of stylesheet references from the settings object.
Function get​_stylesheet​_reference Retrieve a stylesheet reference from the settings object.
Function get​_trim​_footnote​_ref​_space Return whether or not to trim footnote space.
Function new​_document Return a new empty document object.
Function new​_reporter Return a new Reporter object.
Function normalize​_language​_tag Return a list of normalized combinations for a BCP 47 language tag.
Function relative​_path Build and return a path to target, relative to source (both files).
Function split​_escaped​_whitespace Split text on escaped whitespace (null+space or null+newline). Return a list of strings.
Function strip​_combining​_chars Undocumented
Function uniq Undocumented
Function version​_identifier No summary
Variable east​_asian​_widths Mapping of result codes from unicodedata.east_asian_widt() to character column widths.
Variable release​_level​_abbreviations Undocumented
def extract_extension_options(field_list, options_spec):
Return a dictionary mapping extension option names to converted values.
Parameters
field​_listA flat field list without field arguments, where each field body consists of a single paragraph only.
options​_specDictionary mapping known option names to a conversion function such as int or float.
Unknown Field: newfield
exceptions

Exceptions

Unknown Field: exceptions
  • KeyError for unknown option names.
  • ValueError for invalid option values (raised by the conversion
    function).
  • TypeError for invalid option value types (raised by conversion
    function).
  • DuplicateOptionError for duplicate options.
  • BadOptionError for invalid fields.
  • BadOptionDataError for invalid option data (missing name, missing data, bad quotes, etc.).
def extract_options(field_list):
Return a list of option (name, value) pairs from field names & bodies.
Raises
BadOptionError for invalid fields.
BadOptionDataError for invalid option data (missing name, missing data, bad quotes, etc.).
Unknown Field: parameter
field_list: A flat field list, where each field name is a single word and each field body consists of a single paragraph only.
def assemble_option_dict(option_list, options_spec):
Return a mapping of option names to values.
Parameters
option​_listA list of (name, value) pairs (the output of extract_options()).
options​_specDictionary mapping known option names to a conversion function such as int or float.
Unknown Field: newfield
exceptions

Exceptions

Unknown Field: exceptions
  • KeyError for unknown option names.
  • DuplicateOptionError for duplicate options.
  • ValueError for invalid option values (raised by conversion
    function).
  • TypeError for invalid option value types (raised by conversion
    function).
def decode_path(path):

Ensure path is Unicode. Return nodes.reprunicode object.

Decode file/path string in a failsafe manner if not already done.

def extract_name_value(line):
Return a list of (name, value) from a line of the form "name=value ...".
Unknown Field: exception
NameValueError for invalid input (missing name, missing data, bad quotes, etc.).
def new_reporter(source_path, settings):
Return a new Reporter object.
Parameters
source​_pathUndocumented
settings:optparse.Values objectRuntime settings.
source:stringThe path to or description of the source text of the document.
def new_document(source_path, settings=None):
Return a new empty document object.
Parameters
source​_path:stringThe path to or description of the source text of the document.
settings:optparse.Values object

Runtime settings. If none are provided, a default core set will be used. If you will use the document object with any Docutils components, you must provide their default settings as well. For example, if parsing rST, at least provide the rst-parser settings, obtainable as follows:

settings = docutils.frontend.OptionParser(
    components=(docutils.parsers.rst.Parser,)
    ).get_default_values()
def clean_rcs_keywords(paragraph, keyword_substitutions):

Undocumented

def relative_path(source, target):

Build and return a path to target, relative to source (both files).

If there is no common prefix, return the absolute path to target.

def get_stylesheet_reference(settings, relative_to=None):

Retrieve a stylesheet reference from the settings object.

Deprecated. Use get_stylesheet_list() instead to enable specification of multiple stylesheets as a comma-separated list.

def get_stylesheet_list(settings):
Retrieve list of stylesheet references from the settings object.
def find_file_in_dirs(path, dirs):

Search for path in the list of directories dirs.

Return the first expansion that matches an existing file.

def get_trim_footnote_ref_space(settings):

Return whether or not to trim footnote space.

If trim_footnote_reference_space is not None, return it.

If trim_footnote_reference_space is None, return False unless the footnote reference style is 'superscript'.

def get_source_line(node):
Return the "source" and "line" attributes from the node given or from its closest ancestor.
def escape2null(text):
Return a string with escape-backslashes converted to nulls.
def split_escaped_whitespace(text):
Split text on escaped whitespace (null+space or null+newline). Return a list of strings.
def strip_combining_chars(text):

Undocumented

def find_combining_chars(text):

Return indices of all combining chars in Unicode string text.

>>> from docutils.utils import find_combining_chars
>>> find_combining_chars(u'A t̆ab̆lĕ')
[3, 6, 9]
def column_indices(text):

Indices of Unicode string text when skipping combining characters.

>>> from docutils.utils import column_indices
>>> column_indices(u'A t̆ab̆lĕ')
[0, 1, 2, 4, 5, 7, 8]
east_asian_widths: dict[str, int] =
Mapping of result codes from unicodedata.east_asian_widt() to character column widths.
def column_width(text):

Return the column width of text.

Correct len(text) for wide East Asian and combining Unicode chars.

def uniq(L):

Undocumented

def normalize_language_tag(tag):

Return a list of normalized combinations for a BCP 47 language tag.

Example:

>>> from docutils.utils import normalize_language_tag
>>> normalize_language_tag('de_AT-1901')
['de-at-1901', 'de-at', 'de-1901', 'de']
>>> normalize_language_tag('de-CH-x_altquot')
['de-ch-x-altquot', 'de-ch', 'de-x-altquot', 'de']
release_level_abbreviations: dict[str, str] =

Undocumented

def version_identifier(version_info=None):
Return a version identifier string built from version_info, a docutils.VersionInfo namedtuple instance or compatible tuple. If version_info is not provided, by default return a version identifier string based on docutils.__version_info__ (i.e. the current Docutils version).