class documentation

class HTMLTranslator(nodes.NodeVisitor): (source)

Known subclasses: docutils.writers.html4css1.HTMLTranslator, docutils.writers.html5_polyglot.HTMLTranslator

View In Hierarchy

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)
  1. 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.
Method __init__ Undocumented
Method add​_meta Undocumented
Method astext Undocumented
Method attval Cleanse, HTML encode, and return attribute value text.
Method check​_simple​_list Check for a simple list that can be rendered compactly.
Method cloak​_email Try to hide the link text of a email link from harversters.
Method cloak​_mailto Try to hide a mailto: URL from harvesters.
Method depart​_abbreviation Undocumented
Method depart​_acronym Undocumented
Method depart​_address Undocumented
Method depart​_admonition Undocumented
Method depart​_attribution Undocumented
Method depart​_author Undocumented
Method depart​_authors Undocumented
Method depart​_block​_quote Undocumented
Method depart​_bullet​_list Undocumented
Method depart​_caption Undocumented
Method depart​_citation Undocumented
Method depart​_citation​_reference Undocumented
Method depart​_classifier Undocumented
Method depart​_colspec Undocumented
Method depart​_compound Undocumented
Method depart​_contact Undocumented
Method depart​_container Undocumented
Method depart​_copyright Undocumented
Method depart​_date Undocumented
Method depart​_decoration Undocumented
Method depart​_definition Undocumented
Method depart​_definition​_list Undocumented
Method depart​_definition​_list​_item Undocumented
Method depart​_description Undocumented
Method depart​_docinfo Undocumented
Method depart​_docinfo​_item Undocumented
Method depart​_doctest​_block Undocumented
Method depart​_document Undocumented
Method depart​_emphasis Undocumented
Method depart​_entry Undocumented
Method depart​_enumerated​_list Undocumented
Method depart​_field Undocumented
Method depart​_field​_body Undocumented
Method depart​_field​_list Undocumented
Method depart​_field​_name Undocumented
Method depart​_figure Undocumented
Method depart​_footer Undocumented
Method depart​_footnote Undocumented
Method depart​_footnote​_reference Undocumented
Method depart​_generated Undocumented
Method depart​_header Undocumented
Method depart​_image Undocumented
Method depart​_inline Undocumented
Method depart​_label Undocumented
Method depart​_legend Undocumented
Method depart​_line Undocumented
Method depart​_line​_block Undocumented
Method depart​_list​_item Undocumented
Method depart​_literal Undocumented
Method depart​_literal​_block Undocumented
Method depart​_math Undocumented
Method depart​_math​_block Undocumented
Method depart​_meta Undocumented
Method depart​_option Undocumented
Method depart​_option​_argument Undocumented
Method depart​_option​_group Undocumented
Method depart​_option​_list Undocumented
Method depart​_option​_list​_item Undocumented
Method depart​_option​_string Undocumented
Method depart​_organization Undocumented
Method depart​_paragraph Undocumented
Method depart​_problematic Undocumented
Method depart​_reference Undocumented
Method depart​_revision Undocumented
Method depart​_row Undocumented
Method depart​_rubric Undocumented
Method depart​_section Undocumented
Method depart​_sidebar Undocumented
Method depart​_status Undocumented
Method depart​_strong Undocumented
Method depart​_subscript Undocumented
Method depart​_subtitle Undocumented
Method depart​_superscript Undocumented
Method depart​_system​_message Undocumented
Method depart​_table Undocumented
Method depart​_target Undocumented
Method depart​_tbody Undocumented
Method depart​_term Leave the end tag to self.visit_definition(), in case there's a classifier.
Method depart_​Text Undocumented
Method depart​_tgroup Undocumented
Method depart​_thead Undocumented
Method depart​_title Undocumented
Method depart​_title​_reference Undocumented
Method depart​_topic Undocumented
Method depart​_transition Undocumented
Method depart​_version Undocumented
Method emptytag Construct and return an XML-compatible empty tag.
Method encode Encode special characters in text & return.
Method is​_compactable Undocumented
Method set​_class​_on​_child Set class class_ on the visible child no. index of node. Do nothing if node has fewer children than index.
Method starttag Construct and return a start tag given a node (id & class attributes are extracted), tag name, and optional attributes.
Method stylesheet​_call Return code to reference or embed stylesheet file path
Method unimplemented​_visit Undocumented
Method visit​_abbreviation Undocumented
Method visit​_acronym Undocumented
Method visit​_address Undocumented
Method visit​_admonition Undocumented
Method visit​_attribution Undocumented
Method visit​_author Undocumented
Method visit​_authors Undocumented
Method visit​_block​_quote Undocumented
Method visit​_bullet​_list Undocumented
Method visit​_caption Undocumented
Method visit​_citation Undocumented
Method visit​_citation​_reference Undocumented
Method visit​_classifier Undocumented
Method visit​_colspec Undocumented
Method visit​_comment Escape double-dashes in comment text.
Method visit​_compound Undocumented
Method visit​_contact Undocumented
Method visit​_container Undocumented
Method visit​_copyright Undocumented
Method visit​_date Undocumented
Method visit​_decoration Undocumented
Method visit​_definition Undocumented
Method visit​_definition​_list Undocumented
Method visit​_definition​_list​_item Undocumented
Method visit​_description Undocumented
Method visit​_docinfo Undocumented
Method visit​_docinfo​_item Undocumented
Method visit​_doctest​_block Undocumented
Method visit​_document Undocumented
Method visit​_emphasis Undocumented
Method visit​_entry Undocumented
Method visit​_enumerated​_list Undocumented
Method visit​_field Undocumented
Method visit​_field​_body Undocumented
Method visit​_field​_list Undocumented
Method visit​_field​_name Undocumented
Method visit​_figure Undocumented
Method visit​_footer Undocumented
Method visit​_footnote Undocumented
Method visit​_footnote​_reference Undocumented
Method visit​_generated Undocumented
Method visit​_header Undocumented
Method visit​_image Undocumented
Method visit​_inline Undocumented
Method visit​_label Undocumented
Method visit​_legend Undocumented
Method visit​_line Undocumented
Method visit​_line​_block Undocumented
Method visit​_list​_item Undocumented
Method visit​_literal Undocumented
Method visit​_literal​_block Undocumented
Method visit​_math Undocumented
Method visit​_math​_block Undocumented
Method visit​_meta Undocumented
Method visit​_option Undocumented
Method visit​_option​_argument Undocumented
Method visit​_option​_group Undocumented
Method visit​_option​_list Undocumented
Method visit​_option​_list​_item Undocumented
Method visit​_option​_string Undocumented
Method visit​_organization Undocumented
Method visit​_paragraph Undocumented
Method visit​_problematic Undocumented
Method visit​_raw Undocumented
Method visit​_reference Undocumented
Method visit​_revision Undocumented
Method visit​_row Undocumented
Method visit​_rubric Undocumented
Method visit​_section Undocumented
Method visit​_sidebar Undocumented
Method visit​_status Undocumented
Method visit​_strong Undocumented
Method visit​_subscript Undocumented
Method visit​_substitution​_definition Internal only.
Method visit​_substitution​_reference Undocumented
Method visit​_subtitle Undocumented
Method visit​_superscript Undocumented
Method visit​_system​_message Undocumented
Method visit​_table Undocumented
Method visit​_target Undocumented
Method visit​_tbody Undocumented
Method visit​_term Undocumented
Method visit_​Text Undocumented
Method visit​_tgroup Undocumented
Method visit​_thead Undocumented
Method visit​_title Only 6 section levels are supported by HTML.
Method visit​_title​_reference Undocumented
Method visit​_topic Undocumented
Method visit​_transition Undocumented
Method visit​_version Undocumented
Class Variable attribution​_formats Undocumented
Class Variable content​_type Undocumented
Class Variable doctype Undocumented
Class Variable embedded​_stylesheet Undocumented
Class Variable generator Undocumented
Class Variable head​_prefix​_template Undocumented
Class Variable in​_word​_wrap​_point Undocumented
Class Variable lang​_attribute Undocumented
Class Variable math​_tags Undocumented
Class Variable mathjax​_script Undocumented
Class Variable special​_characters Character references for characters with a special meaning in HTML.
Class Variable stylesheet​_link Undocumented
Class Variable words​_and​_spaces Undocumented
Class Variable xml​_declaration Undocumented
Instance Variable author​_in​_authors Undocumented
Instance Variable body Undocumented
Instance Variable body​_pre​_docinfo Undocumented
Instance Variable body​_prefix Undocumented
Instance Variable body​_suffix Undocumented
Instance Variable colspecs Undocumented
Instance Variable compact​_field​_list Undocumented
Instance Variable compact​_p Undocumented
Instance Variable compact​_simple Undocumented
Instance Variable context Heterogeneous stack.
Instance Variable docinfo Undocumented
Instance Variable footer Undocumented
Instance Variable fragment Undocumented
Instance Variable head Undocumented
Instance Variable head​_prefix Undocumented
Instance Variable header Undocumented
Instance Variable html​_body Undocumented
Instance Variable html​_head Undocumented
Instance Variable html​_prolog Undocumented
Instance Variable html​_subtitle Undocumented
Instance Variable html​_title Undocumented
Instance Variable in​_docinfo Undocumented
Instance Variable in​_document​_title Undocumented
Instance Variable in​_footnote​_list Undocumented
Instance Variable in​_mailto Undocumented
Instance Variable in​_sidebar Undocumented
Instance Variable initial​_header​_level Undocumented
Instance Variable language Undocumented
Instance Variable math​_header Undocumented
Instance Variable math​_output Undocumented
Instance Variable math​_output​_options Undocumented
Instance Variable mathjax​_url URL of the MathJax javascript library.
Instance Variable meta Undocumented
Instance Variable section​_level Undocumented
Instance Variable settings Undocumented
Instance Variable stylesheet Undocumented
Instance Variable subtitle Undocumented
Instance Variable title Undocumented
Instance Variable topic​_classes Undocumented

Inherited from NodeVisitor:

Method dispatch​_departure Call self."depart_ + node class name" with node as parameter. If the depart_... method does not exist, call self.unknown_departure.
Method dispatch​_visit Call self."visit_ + node class name" with node as parameter. If the visit_... method does not exist, call self.unknown_visit.
Method unknown​_departure Called before exiting unknown Node types.
Method unknown​_visit Called when entering unknown Node types.
Class Variable optional Tuple containing node class names (as strings).
Instance Variable document Undocumented
def __init__(self, document): (source)
def add_meta(self, tag): (source)

Undocumented

def astext(self): (source)

Undocumented

def attval(self, text, whitespace=re.compile('[\n\r\t\v\f]')): (source)
Cleanse, HTML encode, and return attribute value text.
def check_simple_list(self, node): (source)
Check for a simple list that can be rendered compactly.
def cloak_email(self, addr): (source)
Try to hide the link text of a email link from harversters.
def cloak_mailto(self, uri): (source)
Try to hide a mailto: URL from harvesters.
def depart_abbreviation(self, node): (source)

Undocumented

def depart_acronym(self, node): (source)
def depart_address(self, node): (source)

Undocumented

def depart_admonition(self, node=None): (source)

Undocumented

def depart_attribution(self, node): (source)

Undocumented

def depart_author(self, node): (source)

Undocumented

def depart_block_quote(self, node): (source)

Undocumented

def depart_bullet_list(self, node): (source)

Undocumented

def depart_caption(self, node): (source)
def depart_citation(self, node): (source)

Undocumented

def depart_citation_reference(self, node): (source)

Undocumented

def depart_classifier(self, node): (source)

Undocumented

def depart_colspec(self, node): (source)

Undocumented

def depart_compound(self, node): (source)

Undocumented

def depart_contact(self, node): (source)

Undocumented

def depart_container(self, node): (source)
def depart_copyright(self, node): (source)
def depart_date(self, node): (source)
def depart_decoration(self, node): (source)

Undocumented

def depart_definition(self, node): (source)

Undocumented

def depart_definition_list(self, node): (source)

Undocumented

def depart_definition_list_item(self, node): (source)

Undocumented

def depart_description(self, node): (source)

Undocumented

def depart_docinfo(self, node): (source)

Undocumented

def depart_docinfo_item(self): (source)

Undocumented

def depart_doctest_block(self, node): (source)

Undocumented

def depart_emphasis(self, node): (source)

Undocumented

def depart_entry(self, node): (source)

Undocumented

def depart_enumerated_list(self, node): (source)

Undocumented

def depart_field(self, node): (source)

Undocumented

def depart_field_body(self, node): (source)

Undocumented

def depart_field_list(self, node): (source)

Undocumented

def depart_field_name(self, node): (source)

Undocumented

def depart_figure(self, node): (source)
def depart_footnote(self, node): (source)

Undocumented

def depart_footnote_reference(self, node): (source)

Undocumented

def depart_generated(self, node): (source)

Undocumented

def depart_inline(self, node): (source)
def depart_label(self, node): (source)

Undocumented

def depart_legend(self, node): (source)
def depart_line(self, node): (source)

Undocumented

def depart_line_block(self, node): (source)

Undocumented

def depart_list_item(self, node): (source)

Undocumented

def depart_literal(self, node): (source)
def depart_literal_block(self, node): (source)

Undocumented

def depart_math(self, node): (source)

Undocumented

def depart_math_block(self, node): (source)

Undocumented

def depart_meta(self, node): (source)
def depart_option(self, node): (source)

Undocumented

def depart_option_argument(self, node): (source)

Undocumented

def depart_option_group(self, node): (source)

Undocumented

def depart_option_list(self, node): (source)

Undocumented

def depart_option_list_item(self, node): (source)

Undocumented

def depart_option_string(self, node): (source)

Undocumented

def depart_organization(self, node): (source)
def depart_paragraph(self, node): (source)

Undocumented

def depart_problematic(self, node): (source)

Undocumented

def depart_reference(self, node): (source)

Undocumented

def depart_revision(self, node): (source)

Undocumented

def depart_row(self, node): (source)

Undocumented

def depart_rubric(self, node): (source)

Undocumented

def depart_section(self, node): (source)
def depart_sidebar(self, node): (source)
def depart_status(self, node): (source)

Undocumented

def depart_strong(self, node): (source)

Undocumented

def depart_subscript(self, node): (source)

Undocumented

def depart_subtitle(self, node): (source)

Undocumented

def depart_superscript(self, node): (source)

Undocumented

def depart_system_message(self, node): (source)

Undocumented

def depart_table(self, node): (source)

Undocumented

def depart_target(self, node): (source)

Undocumented

def depart_tbody(self, node): (source)

Undocumented

def depart_term(self, node): (source)
Leave the end tag to self.visit_definition(), in case there's a classifier.
def depart_Text(self, node): (source)

Undocumented

def depart_tgroup(self, node): (source)

Undocumented

def depart_thead(self, node): (source)

Undocumented

def depart_title(self, node): (source)

Undocumented

def depart_title_reference(self, node): (source)

Undocumented

def depart_topic(self, node): (source)
def depart_transition(self, node): (source)

Undocumented

def depart_version(self, node): (source)

Undocumented

def emptytag(self, node, tagname, suffix='\n', **attributes): (source)
Construct and return an XML-compatible empty tag.
def encode(self, text): (source)
Encode special characters in text & return.
def is_compactable(self, node): (source)

Undocumented

def set_class_on_child(self, node, class_, index=0): (source)
Set class class_ on the visible child no. index of node. Do nothing if node has fewer children than index.
def starttag(self, node, tagname, suffix='\n', empty=False, **attributes): (source)
Construct and return a start tag given a node (id & class attributes are extracted), tag name, and optional attributes.
def stylesheet_call(self, path): (source)
Return code to reference or embed stylesheet file path
def unimplemented_visit(self, node): (source)

Undocumented

def visit_abbreviation(self, node): (source)

Undocumented

def visit_acronym(self, node): (source)
def visit_address(self, node): (source)

Undocumented

def visit_admonition(self, node): (source)

Undocumented

def visit_attribution(self, node): (source)

Undocumented

def visit_author(self, node): (source)

Undocumented

def visit_block_quote(self, node): (source)

Undocumented

def visit_bullet_list(self, node): (source)

Undocumented

def visit_caption(self, node): (source)
def visit_citation(self, node): (source)

Undocumented

def visit_citation_reference(self, node): (source)

Undocumented

def visit_classifier(self, node): (source)

Undocumented

def visit_colspec(self, node): (source)

Undocumented

def visit_comment(self, node, sub=re.compile('-(?=-)').sub): (source)
Escape double-dashes in comment text.
def visit_compound(self, node): (source)

Undocumented

def visit_contact(self, node): (source)

Undocumented

def visit_container(self, node): (source)
def visit_copyright(self, node): (source)
def visit_date(self, node): (source)
def visit_decoration(self, node): (source)

Undocumented

def visit_definition(self, node): (source)

Undocumented

def visit_definition_list(self, node): (source)

Undocumented

def visit_definition_list_item(self, node): (source)

Undocumented

def visit_description(self, node): (source)

Undocumented

def visit_docinfo(self, node): (source)

Undocumented

def visit_docinfo_item(self, node, name, meta=True): (source)

Undocumented

def visit_doctest_block(self, node): (source)

Undocumented

def visit_document(self, node): (source)
def visit_emphasis(self, node): (source)

Undocumented

def visit_entry(self, node): (source)

Undocumented

def visit_enumerated_list(self, node): (source)

Undocumented

def visit_field(self, node): (source)

Undocumented

def visit_field_body(self, node): (source)

Undocumented

def visit_field_list(self, node): (source)

Undocumented

def visit_field_name(self, node): (source)

Undocumented

def visit_figure(self, node): (source)
def visit_footer(self, node): (source)
def visit_footnote(self, node): (source)

Undocumented

def visit_footnote_reference(self, node): (source)

Undocumented

def visit_generated(self, node): (source)

Undocumented

def visit_header(self, node): (source)
def visit_inline(self, node): (source)
def visit_label(self, node): (source)

Undocumented

def visit_legend(self, node): (source)
def visit_line(self, node): (source)

Undocumented

def visit_line_block(self, node): (source)

Undocumented

def visit_list_item(self, node): (source)

Undocumented

def visit_literal_block(self, node): (source)

Undocumented

def visit_math(self, node, math_env=''): (source)

Undocumented

def visit_math_block(self, node): (source)

Undocumented

def visit_meta(self, node): (source)
def visit_option(self, node): (source)

Undocumented

def visit_option_argument(self, node): (source)

Undocumented

def visit_option_group(self, node): (source)

Undocumented

def visit_option_list(self, node): (source)

Undocumented

def visit_option_list_item(self, node): (source)

Undocumented

def visit_option_string(self, node): (source)

Undocumented

def visit_organization(self, node): (source)
def visit_paragraph(self, node): (source)

Undocumented

def visit_problematic(self, node): (source)

Undocumented

def visit_raw(self, node): (source)

Undocumented

def visit_reference(self, node): (source)

Undocumented

def visit_revision(self, node): (source)

Undocumented

def visit_row(self, node): (source)

Undocumented

def visit_rubric(self, node): (source)

Undocumented

def visit_status(self, node): (source)

Undocumented

def visit_strong(self, node): (source)

Undocumented

def visit_subscript(self, node): (source)

Undocumented

def visit_substitution_definition(self, node): (source)
Internal only.
def visit_substitution_reference(self, node): (source)

Undocumented

def visit_subtitle(self, node): (source)

Undocumented

def visit_superscript(self, node): (source)

Undocumented

def visit_system_message(self, node): (source)

Undocumented

def visit_table(self, node): (source)

Undocumented

def visit_target(self, node): (source)

Undocumented

def visit_tbody(self, node): (source)

Undocumented

def visit_term(self, node): (source)

Undocumented

def visit_Text(self, node): (source)

Undocumented

def visit_tgroup(self, node): (source)

Undocumented

def visit_thead(self, node): (source)

Undocumented

def visit_title(self, node): (source)
Only 6 section levels are supported by HTML.
def visit_title_reference(self, node): (source)

Undocumented

def visit_topic(self, node): (source)
def visit_transition(self, node): (source)

Undocumented

def visit_version(self, node): (source)

Undocumented

attribution_formats: dict = (source)

Undocumented

content_type: str = (source)

Undocumented

doctype: str = (source)

Undocumented

embedded_stylesheet: str = (source)

Undocumented

generator: str = (source)

Undocumented

head_prefix_template: str = (source)

Undocumented

in_word_wrap_point = (source)

Undocumented

lang_attribute: str = (source)

Undocumented

math_tags: dict = (source)

Undocumented

mathjax_script: str = (source)

Undocumented

special_characters = (source)
Character references for characters with a special meaning in HTML.
stylesheet_link: str = (source)

Undocumented

words_and_spaces = (source)

Undocumented

xml_declaration: str = (source)

Undocumented

author_in_authors: bool = (source)

Undocumented

body: list = (source)

Undocumented

body_pre_docinfo: list = (source)

Undocumented

body_prefix: list[str] = (source)

Undocumented

body_suffix: list[str] = (source)

Undocumented

colspecs: list = (source)

Undocumented

compact_field_list: bool = (source)

Undocumented

compact_p = (source)

Undocumented

compact_simple = (source)

Undocumented

context: list = (source)

Heterogeneous stack.

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

docinfo = (source)

Undocumented

footer: list = (source)

Undocumented

fragment: list = (source)

Undocumented

head = (source)

Undocumented

head_prefix: list = (source)

Undocumented

header: list = (source)

Undocumented

html_body: list = (source)

Undocumented

html_head = (source)

Undocumented

html_prolog: list = (source)

Undocumented

html_subtitle: list = (source)

Undocumented

html_title: list = (source)

Undocumented

in_docinfo: bool = (source)

Undocumented

in_document_title: int = (source)

Undocumented

in_footnote_list: bool = (source)

Undocumented

in_mailto: bool = (source)

Undocumented

initial_header_level = (source)

Undocumented

language = (source)

Undocumented

math_header = (source)

Undocumented

math_output: str = (source)

Undocumented

math_output_options = (source)

Undocumented

mathjax_url = (source)

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.

meta = (source)

Undocumented

section_level: int = (source)

Undocumented

settings = (source)

Undocumented

stylesheet = (source)

Undocumented

subtitle = (source)

Undocumented

title = (source)

Undocumented

topic_classes: list = (source)