docutils.writers._html_base module

common definitions for Docutils HTML writers

class Writer

Bases: Writer

supported = ('html', 'xhtml')

Formats this writer supports.

settings_spec = ('HTML Writer Options', None, (('Specify the template file (UTF-8 encoded). (default: writer dependent)', ['--template'], {'metavar': '<file>'}), ('Comma separated list of stylesheet URLs. Overrides previous --stylesheet and --stylesheet-path settings.', ['--stylesheet'], {'metavar': '<URL[,URL,...]>', 'overrides': 'stylesheet_path', 'validator': <function validate_comma_separated_list>}), ('Comma separated list of stylesheet paths. Relative paths are expanded if a matching file is found in the --stylesheet-dirs. With --link-stylesheet, the path is rewritten relative to the output HTML file. (default: writer dependent)', ['--stylesheet-path'], {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet', 'validator': <function validate_comma_separated_list>}), ('Comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. (default: writer dependent)', ['--stylesheet-dirs'], {'metavar': '<dir[,dir,...]>', 'validator': <function validate_comma_separated_list>}), ('Embed the stylesheet(s) in the output HTML file.  The stylesheet files must be accessible during processing. (default)', ['--embed-stylesheet'], {'action': 'store_true', 'default': 1, 'validator': <function validate_boolean>}), ('Link to the stylesheet(s) in the output HTML file. ', ['--link-stylesheet'], {'action': 'store_false', 'dest': 'embed_stylesheet'}), ('Specify the initial header level. Does not affect document title & subtitle (see --no-doc-title).(default: writer dependent).', ['--initial-header-level'], {'choices': ['1', '2', '3', '4', '5', '6'], 'default': '2', 'metavar': '<level>'}), ('Format for footnote references: one of "superscript" or "brackets". (default: "brackets")', ['--footnote-references'], {'choices': ['superscript', 'brackets'], 'default': 'brackets', 'metavar': '<format>', 'overrides': 'trim_footnote_reference_space'}), ('Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash")', ['--attribution'], {'choices': ['dash', 'parentheses', 'parens', 'none'], 'default': 'dash', 'metavar': '<format>'}), ('Remove extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default)', ['--compact-lists'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Disable compact simple bullet and enumerated lists.', ['--no-compact-lists'], {'action': 'store_false', 'dest': 'compact_lists'}), ('Remove extra vertical whitespace between items of simple field lists. (default)', ['--compact-field-lists'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Disable compact simple field lists.', ['--no-compact-field-lists'], {'action': 'store_false', 'dest': 'compact_field_lists'}), ('Added to standard table classes. Defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid.', ['--table-style'], {'default': ''}), ('Math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "HTML math.css")', ['--math-output'], {'default': 'HTML math.css'}), ('Prepend an XML declaration. ', ['--xml-declaration'], {'action': 'store_true', 'default': False, 'validator': <function validate_boolean>}), ('Omit the XML declaration.', ['--no-xml-declaration'], {'action': 'store_false', 'dest': 'xml_declaration'}), ('Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.', ['--cloak-email-addresses'], {'action': 'store_true', 'validator': <function validate_boolean>})))

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

• Option group title (string or None which implies no group, just a list of single options).

• Description (string or None).

• A sequence of option tuples. Each consists of:

  • Help text (string)

  • List of option strings (e.g. ['-Q', '--quux']).

  • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

    Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

    Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

    See the optparse docs for more details.

• More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

settings_defaults = {'output_encoding_error_handler': 'xmlcharrefreplace'}

A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.

config_section = 'html base writer'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

config_section_dependencies = ('writers', 'html writers')

A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.

visitor_attributes = ('head_prefix', 'head', 'stylesheet', 'body_prefix', 'body_pre_docinfo', 'docinfo', 'body', 'body_suffix', 'title', 'subtitle', 'header', 'footer', 'meta', 'fragment', 'html_prolog', 'html_head', 'html_title', 'html_subtitle', 'html_body')

get_transforms()

Transforms required by this class. Override in subclasses.

translate()

Do final translation of self.document into self.output. Called from write. Override in subclasses.

Usually done with a docutils.nodes.NodeVisitor subclass, in combination with a call to docutils.nodes.Node.walk() or docutils.nodes.Node.walkabout(). The NodeVisitor subclass must support all standard elements (listed in docutils.nodes.node_class_names) and possibly non-standard elements used by the current Reader as well.

apply_template()

interpolation_dict()

assemble_parts()

Assemble the self.parts dictionary. Extend in subclasses.

See <https://docutils.sourceforge.io/docs/api/publisher.html>.

class HTMLTranslator(document)

Bases: NodeVisitor

Generic Docutils to HTML translator.

See the html4css1 and html5_polyglot writers for full featured HTML writers.

Important

The visit_* and depart_* methods use a heterogeneous stack, self.context. When subclassing, make sure to be consistent in its use!

Examples for robust coding:

1. Override both visit_* and depart_* methods, don’t call the parent functions.

2. Extend both and unconditionally call the parent functions:

   def visit_example(self, node):
       if foo:
           self.body.append('<div class="foo">')
       html4css1.HTMLTranslator.visit_example(self, node)
   
   def depart_example(self, node):
       html4css1.HTMLTranslator.depart_example(self, node)
       if foo:
           self.body.append('</div>')
   

3. Extend both, calling the parent functions under the same conditions:

   def visit_example(self, node):
       if foo:
           self.body.append('<div class="foo">
   

‘)

else: # call the parent method

_html_base.HTMLTranslator.visit_example(self, node)

def depart_example(self, node):

if foo:

self.body.append(‘</div>

‘)

else: # call the parent method

_html_base.HTMLTranslator.depart_example(self, node)

4. Extend one method (call the parent), but don’t otherwise use the self.context stack:

   def depart_example(self, node):
       _html_base.HTMLTranslator.depart_example(self, node)
       if foo:
           # implementation-specific code
           # that does not use `self.context`
           self.body.append('</div>
   

‘)

This way, changes in stack use will not bite you.

doctype = '<!DOCTYPE html>\n'

doctype_mathml = '<!DOCTYPE html>\n'

head_prefix_template = '<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%(lang)s" lang="%(lang)s">\n<head>\n'

content_type = '<meta charset="%s" />\n'

generator = '<meta name="generator" content="Docutils 0.20.1: https://docutils.sourceforge.io/" />\n'

documenttag_args = {'CLASS': 'document', 'tagname': 'div'}

mathjax_script = '<script type="text/javascript" src="%s"></script>\n'

mathjax_url = 'file:/usr/share/javascript/mathjax/MathJax.js'

URL of the MathJax javascript library.

The MathJax library ought to be installed on the same server as the rest of the deployed site files and specified in the math-output setting appended to “mathjax”. See Docutils Configuration.

The fallback tries a local MathJax installation at /usr/share/javascript/mathjax/MathJax.js.

stylesheet_link = '<link rel="stylesheet" href="%s" type="text/css" />\n'

embedded_stylesheet = '<style type="text/css">\n\n%s\n</style>\n'

words_and_spaces = re.compile('[^ \\n]+| +|\\n')

in_word_wrap_point = re.compile('.+\\W\\W.+|[-?].+')

lang_attribute = 'lang'

special_characters = {34: '&quot;', 38: '&amp;', 60: '&lt;', 62: '&gt;', 64: '&#64;'}

Character references for characters with a special meaning in HTML.

context

Heterogeneous stack.

Used by visit_* and depart_* functions in conjunction with the tree traversal. Make sure that the pops correspond to the pushes.

astext()

encode(text)

Encode special characters in text & return.

cloak_mailto(uri)

Try to hide a mailto: URL from harvesters.

cloak_email(addr)

Try to hide the link text of a email link from harversters.

attval(text, whitespace=re.compile('[\n\r\t\x0b\x0c]'))

Cleanse, HTML encode, and return attribute value text.

stylesheet_call(path, adjust_path=None)

Return code to reference or embed stylesheet file path

starttag(node, tagname, suffix='\n', empty=False, **attributes)

Construct and return a start tag given a node (id & class attributes are extracted), tag name, and optional attributes.

emptytag(node, tagname, suffix='\n', **attributes)

Construct and return an XML-compatible empty tag.

set_class_on_child(node, class_, index=0)

Set class class_ on the visible child no. index of node. Do nothing if node has fewer children than index.

visit_Text(node)

depart_Text(node)

visit_abbreviation(node)

depart_abbreviation(node)

visit_acronym(node)

depart_acronym(node)

visit_address(node)

depart_address(node)

visit_admonition(node)

depart_admonition(node=None)

attribution_formats = {'dash': ('—', ''), 'none': ('', ''), 'parens': ('(', ')'), 'parentheses': ('(', ')')}

visit_attribution(node)

depart_attribution(node)

visit_author(node)

depart_author(node)

visit_authors(node)

depart_authors(node)

visit_block_quote(node)

depart_block_quote(node)

check_simple_list(node)

Check for a simple list that can be rendered compactly.

is_compactable(node)

visit_bullet_list(node)

depart_bullet_list(node)

visit_caption(node)

depart_caption(node)

visit_citation(node)

depart_citation(node)

visit_citation_reference(node)

depart_citation_reference(node)

visit_classifier(node)

depart_classifier(node)

visit_colspec(node)

depart_colspec(node)

visit_comment(node, sub=<built-in method sub of re.Pattern object>)

Escape double-dashes in comment text.

visit_compound(node)

depart_compound(node)

visit_container(node)

depart_container(node)

visit_contact(node)

depart_contact(node)

visit_copyright(node)

depart_copyright(node)

visit_date(node)

depart_date(node)

visit_decoration(node)

depart_decoration(node)

visit_definition(node)

depart_definition(node)

visit_definition_list(node)

depart_definition_list(node)

visit_definition_list_item(node)

depart_definition_list_item(node)

visit_description(node)

depart_description(node)

visit_docinfo(node)

depart_docinfo(node)

visit_docinfo_item(node, name, meta=True)

depart_docinfo_item()

visit_doctest_block(node)

depart_doctest_block(node)

visit_document(node)

depart_document(node)

visit_emphasis(node)

depart_emphasis(node)

visit_entry(node)

depart_entry(node)

visit_enumerated_list(node)

depart_enumerated_list(node)

visit_field_list(node)

depart_field_list(node)

visit_field(node)

depart_field(node)

visit_field_name(node)

depart_field_name(node)

visit_field_body(node)

depart_field_body(node)

visit_figure(node)

depart_figure(node)

visit_footer(node)

depart_footer(node)

visit_footnote(node)

depart_footnote(node)

visit_footnote_reference(node)

depart_footnote_reference(node)

visit_generated(node)

depart_generated(node)

visit_header(node)

depart_header(node)

visit_image(node)

depart_image(node)

visit_inline(node)

depart_inline(node)

visit_label(node)

depart_label(node)

visit_legend(node)

depart_legend(node)

visit_line(node)

depart_line(node)

visit_line_block(node)

depart_line_block(node)

visit_list_item(node)

depart_list_item(node)

visit_literal(node)

depart_literal(node)

visit_literal_block(node)

depart_literal_block(node)

math_tags = {'html': ('div', 'span', 'formula'), 'latex': ('pre', 'tt', 'math'), 'mathjax': ('div', 'span', 'math'), 'mathml': ('div', '', '')}

visit_math(node, math_env='')

depart_math(node)

visit_math_block(node)

depart_math_block(node)

visit_meta(node)

depart_meta(node)

visit_option(node)

depart_option(node)

visit_option_argument(node)

depart_option_argument(node)

visit_option_group(node)

depart_option_group(node)

visit_option_list(node)

depart_option_list(node)

visit_option_list_item(node)

depart_option_list_item(node)

visit_option_string(node)

depart_option_string(node)

visit_organization(node)

depart_organization(node)

visit_paragraph(node)

depart_paragraph(node)

visit_problematic(node)

depart_problematic(node)

visit_raw(node)

visit_reference(node)

depart_reference(node)

visit_revision(node)

depart_revision(node)

visit_row(node)

depart_row(node)

visit_rubric(node)

depart_rubric(node)

visit_section(node)

depart_section(node)

visit_sidebar(node)

depart_sidebar(node)

visit_status(node)

depart_status(node)

visit_strong(node)

depart_strong(node)

visit_subscript(node)

depart_subscript(node)

visit_substitution_definition(node)

Internal only.

visit_substitution_reference(node)

visit_subtitle(node)

depart_subtitle(node)

visit_superscript(node)

depart_superscript(node)

visit_system_message(node)

depart_system_message(node)

visit_table(node)

depart_table(node)

visit_target(node)

depart_target(node)

visit_tbody(node)

depart_tbody(node)

visit_term(node)

depart_term(node)

visit_tgroup(node)

depart_tgroup(node)

visit_thead(node)

depart_thead(node)

section_title_tags(node)

visit_title(node)

depart_title(node)

visit_title_reference(node)

depart_title_reference(node)

visit_topic(node)

depart_topic(node)

visit_transition(node)

depart_transition(node)

visit_version(node)

depart_version(node)

unimplemented_visit(node)

class SimpleListChecker(document)

Bases: GenericNodeVisitor

Raise nodes.NodeFound if non-simple list item is encountered.

Here “simple” means a list item containing nothing other than a single paragraph, a simple list, or a paragraph followed by a simple list.

This version also checks for simple field lists and docinfo.

default_visit(node)

Override for generic, uniform traversals.

visit_list_item(node)

pass_node(node)

ignore_node(node)

visit_Text(node)

visit_paragraph(node)

visit_bullet_list(node)

visit_enumerated_list(node)

visit_docinfo(node)

visit_author(node)

visit_authors(node)

visit_address(node)

visit_contact(node)

visit_copyright(node)

visit_date(node)

visit_organization(node)

visit_status(node)

visit_version(node)

visit_definition_list(node)

visit_definition_list_item(node)

visit_term(node)

visit_classifier(node)

visit_definition(node)

visit_field_list(node)

visit_field(node)

visit_field_body(node)

visit_field_name(node)

visit_comment(node)

visit_substitution_definition(node)

visit_target(node)

visit_pending(node)