class documentation

class HTMLTranslator(writers._html_base.HTMLTranslator):

Known subclasses: docutils.writers.pep_html.HTMLTranslator, docutils.writers.s5_html.S5HTMLTranslator

View In Hierarchy

The html4css1 writer has been optimized to produce visually compact lists (less vertical whitespace). HTML's mixed content models allow list items to contain "<li><p>body elements</p></li>" or "<li>just text</li>" or even "<li>text<p>and body elements</p>combined</li>", each with different effects. It would be best to stick with strict body elements in list items, but they affect vertical spacing in older browsers (although they really shouldn't). The html5_polyglot writer solves this using CSS2.

Here is an outline of the optimization:

  • Check for and omit <p> tags in "simple" lists: list items contain either a single paragraph, a nested simple list, or a paragraph followed by a nested simple list. This means that this list can be compact:

    • Item 1.
    • Item 2.

    But this list cannot be compact:

    • Item 1.

      This second paragraph forces space between list items.

    • Item 2.

  • In non-list contexts, omit <p> tags on a paragraph if that paragraph is the only child of its parent (footnotes & citations are allowed a label first).

  • Regardless of the above, in definitions, table cells, field bodies, option descriptions, and list items, mark the first child with 'class="first"' and the last child with 'class="last"'. The stylesheet sets the margins (top & bottom respectively) to 0 for these elements.

The no_compact_lists setting (--no-compact-lists command-line option) disables list whitespace optimization.

Method depart​_address Undocumented
Method depart​_admonition Undocumented
Method depart​_author Undocumented
Method depart​_authors Undocumented
Method depart​_citation Undocumented
Method depart​_citation​_reference Undocumented
Method depart​_classifier Undocumented
Method depart​_colspec Undocumented
Method depart​_compound 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​_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​_footnote Undocumented
Method depart​_footnote​_reference Undocumented
Method depart​_image Undocumented
Method depart​_label Undocumented
Method depart​_list​_item Undocumented
Method depart​_literal Undocumented
Method depart​_literal​_block Undocumented
Method depart​_option​_group Undocumented
Method depart​_option​_list Undocumented
Method depart​_option​_list​_item Undocumented
Method depart​_paragraph Undocumented
Method depart​_sidebar Undocumented
Method depart​_subscript Undocumented
Method depart​_subtitle Undocumented
Method depart​_superscript Undocumented
Method depart​_system​_message Undocumented
Method depart​_table Undocumented
Method depart​_tbody Undocumented
Method depart​_term Undocumented
Method depart​_thead Undocumented
Method footnote​_backrefs Undocumented
Method is​_compactable Undocumented
Method section​_title​_tags Undocumented
Method set​_first​_last Undocumented
Method should​_be​_compact​_paragraph Determine if the <p> tags around paragraph node can be omitted.
Method visit​_address Undocumented
Method visit​_admonition Undocumented
Method visit​_author Undocumented
Method visit​_authors Undocumented
Method visit​_citation Undocumented
Method visit​_citation​_reference Undocumented
Method visit​_classifier Undocumented
Method visit​_colspec Undocumented
Method visit​_compound 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​_entry Undocumented
Method visit​_enumerated​_list The 'start' attribute does not conform to HTML 4.01's strict.dtd, but cannot be emulated in CSS1 (HTML 5 reincludes it).
Method visit​_field Undocumented
Method visit​_field​_body Undocumented
Method visit​_field​_list Undocumented
Method visit​_field​_name Undocumented
Method visit​_footnote Undocumented
Method visit​_footnote​_reference Undocumented
Method visit​_generated Undocumented
Method visit​_image Undocumented
Method visit​_label Undocumented
Method visit​_list​_item Undocumented
Method visit​_literal Undocumented
Method visit​_literal​_block Undocumented
Method visit​_option​_group Undocumented
Method visit​_option​_list Undocumented
Method visit​_option​_list​_item Undocumented
Method visit​_paragraph Undocumented
Method visit​_sidebar Undocumented
Method visit​_subscript Undocumented
Method visit​_subtitle Undocumented
Method visit​_superscript Undocumented
Method visit​_system​_message Undocumented
Method visit​_table Undocumented
Method visit​_tbody Undocumented
Method visit​_term Undocumented
Method visit​_thead Undocumented
Class Variable attribution​_formats Undocumented
Class Variable content​_type Undocumented
Class Variable content​_type​_mathml Undocumented
Class Variable doctype Undocumented
Class Variable object​_image​_types Undocumented
Class Variable special​_characters Character references for characters with a special meaning in HTML.
Instance Variable author​_in​_authors Undocumented
Instance Variable body Undocumented
Instance Variable compact​_field​_list Undocumented
Instance Variable compact​_p Undocumented
Instance Variable compact​_simple Undocumented
Instance Variable docinfo Undocumented
Instance Variable in​_docinfo Undocumented
Instance Variable in​_document​_title Undocumented
Instance Variable in​_sidebar Undocumented
Instance Variable subtitle Undocumented

Inherited from HTMLTranslator:

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​_attribution Undocumented
Method depart​_block​_quote Undocumented
Method depart​_bullet​_list Undocumented
Method depart​_caption Undocumented
Method depart​_contact Undocumented
Method depart​_container Undocumented
Method depart​_copyright Undocumented
Method depart​_date Undocumented
Method depart​_decoration Undocumented
Method depart​_document Undocumented
Method depart​_emphasis Undocumented
Method depart​_figure Undocumented
Method depart​_footer Undocumented
Method depart​_generated Undocumented
Method depart​_header Undocumented
Method depart​_inline Undocumented
Method depart​_legend Undocumented
Method depart​_line Undocumented
Method depart​_line​_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​_string Undocumented
Method depart​_organization 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​_status Undocumented
Method depart​_strong Undocumented
Method depart​_target Undocumented
Method depart_​Text Undocumented
Method depart​_tgroup 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 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​_attribution Undocumented
Method visit​_block​_quote Undocumented
Method visit​_bullet​_list Undocumented
Method visit​_caption Undocumented
Method visit​_comment Escape double-dashes in comment text.
Method visit​_contact Undocumented
Method visit​_container Undocumented
Method visit​_copyright Undocumented
Method visit​_date Undocumented
Method visit​_decoration Undocumented
Method visit​_document Undocumented
Method visit​_emphasis Undocumented
Method visit​_figure Undocumented
Method visit​_footer Undocumented
Method visit​_header Undocumented
Method visit​_inline Undocumented
Method visit​_legend Undocumented
Method visit​_line Undocumented
Method visit​_line​_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​_string Undocumented
Method visit​_organization 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​_status Undocumented
Method visit​_strong Undocumented
Method visit​_substitution​_definition Internal only.
Method visit​_substitution​_reference Undocumented
Method visit​_target Undocumented
Method visit_​Text Undocumented
Method visit​_tgroup Undocumented
Method visit​_title Undocumented
Method visit​_title​_reference Undocumented
Method visit​_topic Undocumented
Method visit​_transition Undocumented
Method visit​_version 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 stylesheet​_link Undocumented
Class Variable words​_and​_spaces Undocumented
Class Variable xml​_declaration Undocumented
Instance Variable body​_pre​_docinfo Undocumented
Instance Variable body​_prefix Undocumented
Instance Variable body​_suffix Undocumented
Instance Variable colspecs Undocumented
Instance Variable context Heterogeneous stack.
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 image​_loading Undocumented
Instance Variable in​_mailto 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 title Undocumented

Inherited from NodeVisitor (via HTMLTranslator):

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 depart_address(self, node):
def depart_admonition(self, node=None):
def depart_author(self, node):
def depart_authors(self, node):
def depart_citation(self, node):
def depart_citation_reference(self, node):
def depart_classifier(self, node):
def depart_colspec(self, node):
def depart_compound(self, node):
def depart_definition(self, node):
def depart_definition_list(self, node):
def depart_definition_list_item(self, node):
def depart_description(self, node):
def depart_docinfo(self, node):
def depart_docinfo_item(self):
def depart_doctest_block(self, node):
def depart_entry(self, node):
def depart_enumerated_list(self, node):
def depart_field(self, node):
def depart_field_body(self, node):
def depart_field_list(self, node):
def depart_field_name(self, node):
def depart_footnote(self, node):
def depart_footnote_reference(self, node):
def depart_image(self, node):
def depart_label(self, node):
def depart_list_item(self, node):
def depart_literal(self, node):
def depart_literal_block(self, node):
def depart_option_group(self, node):
def depart_option_list(self, node):
def depart_option_list_item(self, node):
def depart_paragraph(self, node):
def depart_sidebar(self, node):
def depart_subscript(self, node):
def depart_subtitle(self, node):
def depart_superscript(self, node):
def depart_system_message(self, node):
def depart_table(self, node):
def depart_tbody(self, node):
def depart_term(self, node):
def depart_thead(self, node):
def footnote_backrefs(self, node):

Undocumented

def is_compactable(self, node):
def section_title_tags(self, node):
def set_first_last(self, node):

Undocumented

def should_be_compact_paragraph(self, node):
Determine if the <p> tags around paragraph node can be omitted.
def visit_address(self, node):
def visit_admonition(self, node):
def visit_author(self, node):
def visit_authors(self, node):
def visit_citation(self, node):
def visit_citation_reference(self, node):
def visit_classifier(self, node):
def visit_colspec(self, node):
def visit_compound(self, node):
def visit_definition(self, node):
def visit_definition_list(self, node):
def visit_definition_list_item(self, node):
def visit_description(self, node):
def visit_docinfo(self, node):
def visit_docinfo_item(self, node, name, meta=True):
def visit_doctest_block(self, node):
def visit_entry(self, node):
def visit_enumerated_list(self, node):
The 'start' attribute does not conform to HTML 4.01's strict.dtd, but cannot be emulated in CSS1 (HTML 5 reincludes it).
def visit_field(self, node):
def visit_field_body(self, node):
def visit_field_list(self, node):
def visit_field_name(self, node):
def visit_footnote(self, node):
def visit_footnote_reference(self, node):
def visit_generated(self, node):
def visit_image(self, node):
def visit_label(self, node):
def visit_list_item(self, node):
def visit_literal(self, node):
def visit_literal_block(self, node):
def visit_option_group(self, node):
def visit_option_list(self, node):
def visit_option_list_item(self, node):
def visit_paragraph(self, node):
def visit_sidebar(self, node):
def visit_subscript(self, node):
def visit_subtitle(self, node):
def visit_superscript(self, node):
def visit_system_message(self, node):
def visit_table(self, node):
def visit_tbody(self, node):
def visit_term(self, node):
def visit_thead(self, node):
attribution_formats: dict =
content_type: str =
content_type_mathml: str =

Undocumented

doctype: str =
object_image_types: dict[str, str] =

Undocumented

special_characters =
Character references for characters with a special meaning in HTML.
author_in_authors: bool =
body: list =
compact_field_list =
compact_simple =
in_docinfo: bool =
in_document_title: int =
in_sidebar: bool =