RestructuredText Html Writer, based upon the one provided
with docutils.
- Imports:
- Image, docutils, os, os.path, re, sys, time, types
- Classes:
- HTMLTranslator(nodes.NodeVisitor): This HTML 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 browsers (although they really
shouldn't).
- SimpleListChecker(nodes.GenericNodeVisitor): Raise nodes.NodeFound if non-simple list item is encountered.
- Writer(writers.Writer):
- Attributes:
- Image = None
- __docformat__ = 'reStructuredText'
Back to htmlwriter
- Bases:
- nodes.NodeVisitor
This HTML 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 browsers (although they really
shouldn't).
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:
But this list cannot be compact:
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.
- Methods:
- __init__(self, document):
- add_meta(self, tag):
- astext(self):
- attval(self, text, whitespace=re.compile('[\n\r\t\x0b\x0c]')): Cleanse, HTML encode, and return attribute value text.
- check_simple_list(self, node): Check for a simple list that can be rendered compactly.
- cloak_email(self, addr): Try to hide the link text of a email link from harversters.
- cloak_mailto(self, uri): Try to hide a mailto: URL from harvesters.
- depart_Text(self, node):
- depart_abbreviation(self, node):
- depart_acronym(self, node):
- depart_address(self, node):
- depart_admonition(self, node=None):
- depart_attention(self, node):
- depart_attribution(self, node):
- depart_author(self, node):
- depart_authors(self, node):
- depart_block_quote(self, node):
- depart_bullet_list(self, node):
- depart_caption(self, node):
- depart_caution(self, node):
- depart_citation(self, node):
- depart_citation_reference(self, node):
- depart_classifier(self, node):
- depart_colspec(self, node):
- depart_compound(self, node):
- depart_contact(self, node):
- depart_container(self, node):
- depart_copyright(self, node):
- depart_danger(self, node):
- depart_date(self, node):
- depart_decoration(self, node):
- depart_definition(self, node):
- depart_definition_list(self, node):
- depart_definition_list_item(self, node):
- depart_description(self, node):
- depart_docinfo(self, node):
- depart_docinfo_item(self):
- depart_doctest_block(self, node):
- depart_document(self, node):
- depart_emphasis(self, node):
- depart_entry(self, node):
- depart_enumerated_list(self, node):
- depart_error(self, node):
- depart_field(self, node):
- depart_field_body(self, node):
- depart_field_list(self, node):
- depart_field_name(self, node):
- depart_figure(self, node):
- depart_footer(self, node):
- depart_footnote(self, node):
- depart_footnote_reference(self, node):
- depart_generated(self, node):
- depart_header(self, node):
- depart_hint(self, node):
- depart_image(self, node):
- depart_important(self, node):
- depart_inline(self, node):
- depart_label(self, node):
- depart_legend(self, node):
- depart_line(self, node):
- depart_line_block(self, node):
- depart_list_item(self, node):
- depart_literal_block(self, node):
- depart_meta(self, node):
- depart_note(self, node):
- depart_option(self, node):
- depart_option_argument(self, node):
- depart_option_group(self, node):
- depart_option_list(self, node):
- depart_option_list_item(self, node):
- depart_option_string(self, node):
- depart_organization(self, node):
- depart_paragraph(self, node):
- depart_problematic(self, node):
- depart_reference(self, node):
- depart_revision(self, node):
- depart_row(self, node):
- depart_rubric(self, node):
- depart_section(self, node):
- depart_sidebar(self, node):
- depart_status(self, node):
- depart_strong(self, node):
- depart_subscript(self, node):
- depart_subtitle(self, node):
- depart_superscript(self, node):
- depart_system_message(self, node):
- depart_table(self, node):
- depart_target(self, node):
- depart_tbody(self, node):
- depart_term(self, node): Leave the end tag to self.visit_definition(), in case there's a
classifier.
- depart_tgroup(self, node):
- depart_thead(self, node):
- depart_tip(self, node):
- depart_title(self, node):
- depart_title_reference(self, node):
- depart_topic(self, node):
- depart_transition(self, node):
- depart_version(self, node):
- depart_warning(self, node):
- emptytag(self, node, tagname, suffix='\n', **attributes): Construct and return an XML-compatible empty tag.
- encode(self, text): Encode special characters in text & return.
- footnote_backrefs(self, node):
- is_compactable(self, node):
- set_class_on_child(self, node, class_, index=0): Set class class_ on the visible child no. index of node.
Do nothing if node has fewer children than index.
- set_first_last(self, node):
- should_be_compact_paragraph(self, node): Determine if the <p> tags around paragraph node can be omitted.
- start_tag_with_title(self, node, tagname, **atts): ID and NAME attributes will be handled in the title.
- starttag(self, node, tagname, suffix='\n', empty=0, **attributes): Construct and return a start tag given a node (id & class attributes
are extracted), tag name, and optional attributes.
- unimplemented_visit(self, node):
- visit_Text(self, node):
- visit_abbreviation(self, node):
- visit_acronym(self, node):
- visit_address(self, node):
- visit_admonition(self, node, name=''):
- visit_attention(self, node):
- visit_attribution(self, node):
- visit_author(self, node):
- visit_authors(self, node):
- visit_block_quote(self, node):
- visit_bullet_list(self, node):
- visit_caption(self, node):
- visit_caution(self, node):
- visit_citation(self, node):
- visit_citation_reference(self, node):
- visit_classifier(self, node):
- visit_colspec(self, node):
- visit_comment(self, node, sub=re.compile('-(?=-)').sub): Escape double-dashes in comment text.
- visit_compound(self, node):
- visit_contact(self, node):
- visit_container(self, node):
- visit_copyright(self, node):
- visit_danger(self, node):
- visit_date(self, node):
- visit_decoration(self, node):
- visit_definition(self, node):
- visit_definition_list(self, node):
- visit_definition_list_item(self, node):
- visit_description(self, node):
- visit_docinfo(self, node):
- visit_docinfo_item(self, node, name, meta=1):
- visit_doctest_block(self, node):
- visit_document(self, node):
- visit_emphasis(self, node):
- visit_entry(self, node):
- visit_enumerated_list(self, node): The 'start' attribute does not conform to HTML 4.01's strict.dtd, but
CSS1 doesn't help. CSS2 isn't widely enough supported yet to be
usable.
- visit_error(self, node):
- visit_field(self, node):
- visit_field_body(self, node):
- visit_field_list(self, node):
- visit_field_name(self, node):
- visit_figure(self, node):
- visit_footer(self, node):
- visit_footnote(self, node):
- visit_footnote_reference(self, node):
- visit_generated(self, node):
- visit_header(self, node):
- visit_hint(self, node):
- visit_image(self, node):
- visit_important(self, node):
- visit_inline(self, node):
- visit_label(self, node):
- visit_legend(self, node):
- visit_line(self, node):
- visit_line_block(self, node):
- visit_list_item(self, node):
- visit_literal(self, node): Process text to prevent tokens from wrapping.
- visit_literal_block(self, node):
- visit_meta(self, node):
- visit_note(self, node):
- visit_option(self, node):
- visit_option_argument(self, node):
- visit_option_group(self, node):
- visit_option_list(self, node):
- visit_option_list_item(self, node):
- visit_option_string(self, node):
- visit_organization(self, node):
- visit_paragraph(self, node):
- visit_problematic(self, node):
- visit_raw(self, node):
- visit_reference(self, node):
- visit_revision(self, node):
- visit_row(self, node):
- visit_rubric(self, node):
- visit_section(self, node):
- visit_sidebar(self, node):
- visit_status(self, node):
- visit_strong(self, node):
- visit_subscript(self, node):
- visit_substitution_definition(self, node): Internal only.
- visit_substitution_reference(self, node):
- visit_subtitle(self, node):
- visit_superscript(self, node):
- visit_system_message(self, node):
- visit_table(self, node):
- visit_target(self, node):
- visit_tbody(self, node):
- visit_term(self, node):
- visit_tgroup(self, node):
- visit_thead(self, node):
- visit_tip(self, node):
- visit_title(self, node, move_ids=1): Only 6 section levels are supported by HTML.
- visit_title_reference(self, node):
- visit_topic(self, node):
- visit_transition(self, node):
- visit_version(self, node):
- visit_warning(self, node):
- write_colspecs(self):
- Attributes:
- attribution_formats = { 'dash' : ('—', ''), 'parentheses' : ('(', ')'), 'parens' : ('(', ')'), 'none' : ('', '') }
- content_type = '<meta http-equiv="Content-Type" content="text/html; charset=%s" />\n'
- doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n'
- embedded_stylesheet = '<style type="text/css">\n\n%s\n</style>\n'
- generator = '<meta name="generator" content="Docutils %s: http://docutils.sourceforge.net/" />\n'
- head_prefix_template = '<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%s" lang="%s">\n<head>\n'
- named_tags = ['a', 'applet', 'form', 'frame', 'iframe', 'img', 'map']
- stylesheet_link = '<link rel="stylesheet" href="%s" type="text/css" />\n'
- words_and_spaces = re.compile('\\S+| +|\\n')
- xml_declaration = '<?xml version="1.0" encoding="%s" ?>\n'
Back to htmlwriter
- Bases:
- nodes.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.
- Methods:
- default_visit(self, node):
- invisible_visit(self, node): Invisible nodes should be ignored.
- visit_bullet_list(self, node):
- visit_enumerated_list(self, node):
- visit_list_item(self, node):
- visit_paragraph(self, node):
- Attributes:
- visit_comment = invisible_visit
- visit_pending = invisible_visit
- visit_substitution_definition = invisible_visit
- visit_target = invisible_visit
Back to htmlwriter
- Bases:
- writers.Writer
- Methods:
- __init__(self):
- assemble_parts(self):
- translate(self):
- Attributes:
- config_section = 'html4css1 writer'
- config_section_dependencies = ('writers',)
- default_stylesheet = 'html4css1.css'
- default_stylesheet_path = utils.relative_path(os.path.join(os.getcwd(), 'dummy'), os.path.join(os.path.dirname(__file__), default_stylesheet))
- relative_path_settings = ('stylesheet_path',)
- settings_defaults = { 'output_encoding_error_handler' : 'xmlcharrefreplace' }
- settings_spec = ('HTML-Specific Options', None, (('Specify a stylesheet URL, used verbatim. Overrides --stylesheet-path.', ['--stylesheet'], { 'metavar' : '<URL>', 'overrides' : 'stylesheet_path' }), ('Specify a stylesheet file, relative to the current working directory. The path is adjusted relative to the output HTML file. Overrides --stylesheet. Default: "%s"' % default_stylesheet_path, ['--stylesheet-path'], { 'metavar' : '<file>', 'overrides' : 'stylesheet', 'default' : default_stylesheet_path }), ('Embed the stylesheet in the output HTML file. The stylesheet file must be accessible during processing (--stylesheet-path is recommended). This is the default.', ['--embed-stylesheet'], { 'default' : False, 'action' : 'store_true', 'validator' : frontend.validate_boolean }), ('Link to the stylesheet in the output HTML file. Default: embed the stylesheet, do not link to it.', ['--link-stylesheet'], { 'dest' : 'embed_stylesheet', 'action' : 'store_false', 'validator' : frontend.validate_boolean }), ('Specify the initial header level. Default is 1 for "<h1>". Does not affect document title & subtitle (see --no-doc-title).', ['--initial-header-level'], { 'choices' : '1 2 3 4 5 6'.split(), 'default' : '1', 'metavar' : '<level>' }), ('Specify the maximum width (in characters) for one-column field names. Longer field names will span an entire row of the table used to render the field list. Default is 14 characters. Use 0 for "no limit".', ['--field-name-limit'], { 'default' : 14, 'metavar' : '<level>', 'validator' : frontend.validate_nonnegative_int }), ('Specify the maximum width (in characters) for options in option lists. Longer options will span an entire row of the table used to render the option list. Default is 14 characters. Use 0 for "no limit".', ['--option-limit'], { 'default' : 14, 'metavar' : '<level>', 'validator' : frontend.validate_nonnegative_int }), ('Format for footnote references: one of "superscript" or "brackets". Default is "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 is "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: enabled.', ['--compact-lists'], { 'default' : 1, 'action' : 'store_true', 'validator' : frontend.validate_boolean }), ('Disable compact simple bullet and enumerated lists.', ['--no-compact-lists'], { 'dest' : 'compact_lists', 'action' : 'store_false' }), ('Remove extra vertical whitespace between items of simple field lists. Default: enabled.', ['--compact-field-lists'], { 'default' : 1, 'action' : 'store_true', 'validator' : frontend.validate_boolean }), ('Disable compact simple field lists.', ['--no-compact-field-lists'], { 'dest' : 'compact_field_lists', 'action' : 'store_false' }), ('Omit the XML declaration. Use with caution.', ['--no-xml-declaration'], { 'dest' : 'xml_declaration', 'default' : 1, 'action' : 'store_false', 'validator' : frontend.validate_boolean }), ('Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.', ['--cloak-email-addresses'], { 'action' : 'store_true', 'validator' : frontend.validate_boolean })))
- supported = ('html', 'html4css1', 'xhtml')