docutils.writers.html5_polyglot package

Plain HyperText Markup Language document tree Writer.

The output conforms to the HTML 5 specification.

The cascading style sheet “minimal.css” is required for proper viewing, the style sheet “plain.css” improves reading experience.

class Writer

Bases: Writer

supported = ('html5', 'xhtml', 'html')

Formats this writer supports.

default_stylesheets = ['minimal.css', 'plain.css']

default_stylesheet_dirs = ['.', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot']

default_template = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot/template.txt')

settings_spec = ('HTML Writer Options', None, (('Template file. (UTF-8 encoded, default: "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot/template.txt")', ['--template'], {'default': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot/template.txt'), '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: "minimal.css,plain.css")', ['--stylesheet-path'], {'default': ['minimal.css', 'plain.css'], '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: ".,/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot")', ['--stylesheet-dirs'], {'default': ['.', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot'], '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: 2 for "<h2>")', ['--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>})), 'HTML5 Writer Options', '', (('SUPPRESSHELP', ['--embed-images'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('SUPPRESSHELP', ['--link-images'], {'action': 'store_false', 'dest': 'embed_images'}), ('Suggest at which point images should be loaded: "embed", "link" (default), or "lazy".', ['--image-loading'], {'choices': ('embed', 'link', 'lazy')}), ('Append a self-link to section headings.', ['--section-self-link'], {'action': 'store_true', 'default': 0}), ('Do not append a self-link to section headings. (default)', ['--no-section-self-link'], {'action': 'store_false', 'dest': 'section_self_link'})))

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.

config_section = 'html5 writer'

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

class HTMLTranslator(document)

Bases: HTMLTranslator

This writer generates polyglot markup: HTML5 that is also valid XML.

Safe subclassing: when overriding, treat visit_* and depart_* methods as a unit to prevent breaks due to internal changes. See the docstring of docutils.writers._html_base.HTMLTranslator for details and examples.

documenttag_args = {'tagname': 'main'}

visit_acronym(node)

depart_acronym(node)

visit_authors(node)

depart_authors(node)

visit_caption(node)

depart_caption(node)

supported_block_tags = {'del', 'ins'}

visit_container(node)

depart_container(node)

visit_copyright(node)

depart_copyright(node)

visit_date(node)

depart_date(node)

visit_figure(node)

depart_figure(node)

visit_footer(node)

depart_footer(node)

visit_header(node)

depart_header(node)

videotypes = ('video/mp4', 'video/webm', 'video/ogg')

visit_image(node)

depart_image(node)

supported_inline_tags = {'b', 'bdi', 'code', 'del', 'dfn', 'i', 'ins', 'kbd', 'mark', 'q', 's', 'samp', 'small', 'u', 'var'}

visit_inline(node)

depart_inline(node)

visit_legend(node)

depart_legend(node)

visit_literal(node)

depart_literal(node)

visit_meta(node)

depart_meta(node)

visit_organization(node)

depart_organization(node)

visit_section(node)

depart_section(node)

visit_sidebar(node)

depart_sidebar(node)

visit_topic(node)

depart_topic(node)

section_title_tags(node)