docutils.writers.pep_html package

PEP HTML Writer.

class Writer[source]

Bases: Writer

default_stylesheet = 'pep.css'
default_stylesheet_path = '../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/pep.css'
default_template = 'template.txt'
default_template_path = '../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/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/html4css1/template.txt")', ['--template'], {'default': '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1/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: "html4css1.css")', ['--stylesheet-path'], {'default': ['html4css1.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/html4css1,/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/html4css1', '/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: 1 for "<h1>")', ['--initial-header-level'], {'choices': ['1', '2', '3', '4', '5', '6'], 'default': '1', '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 (default). ', ['--xml-declaration'], {'action': 'store_true', 'default': True, '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>})), 'HTML4 Writer Options', '', (('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': <function 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': <function validate_nonnegative_int>})), 'PEP/HTML Writer Options', 'For the PEP/HTML writer, the default value for the --stylesheet-path option is "../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/pep.css", and the default value for --template is "../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/template.txt". See HTML Writer Options above.', (('Python\'s home URL.  Default is "https://www.python.org".', ['--python-home'], {'default': 'https://www.python.org', 'metavar': '<URL>'}), ('Home URL prefix for PEPs.  Default is "." (current directory).', ['--pep-home'], {'default': '.', 'metavar': '<URL>'}), ('SUPPRESSHELP', ['--no-random'], {'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_default_overrides = {'stylesheet_path': '../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/pep.css', 'template': '../../../../envs/latest/lib/python3.12/site-packages/docutils/writers/pep_html/template.txt'}

A dictionary of auxiliary defaults, to override defaults for settings defined in other components’ setting_specs. Override in subclasses.

relative_path_settings = ('template',)

Settings containing filesystem paths. Override in subclasses. Settings listed here are to be interpreted relative to the current working directory.

config_section = 'pep_html writer'

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

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

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.

interpolation_dict()[source]
assemble_parts()[source]

Assemble the self.parts dictionary. Extend in subclasses.

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

class HTMLTranslator(document)[source]

Bases: HTMLTranslator

depart_field_list(node)[source]