docutils.writers.s5_html package

S5/HTML Slideshow Writer.

find_theme(name)

class Writer

Bases: Writer

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>})), 'S5 Slideshow Specific Options', 'For the S5/HTML writer, the --no-toc-backlinks option (defined in General Docutils Options above) is the default, and should not be changed.', (('Specify an installed S5 theme by name.  Overrides --theme-url.  The default theme name is "default".  The theme files will be copied into a "ui/<theme>" directory, in the same directory as the destination file (output HTML).  Note that existing theme files will not be overwritten (unless --overwrite-theme-files is used).', ['--theme'], {'default': 'default', 'metavar': '<name>', 'overrides': 'theme_url'}), ('Specify an S5 theme URL.  The destination file (output HTML) will link to this theme; nothing will be copied.  Overrides --theme.', ['--theme-url'], {'metavar': '<URL>', 'overrides': 'theme'}), ('Allow existing theme files in the ``ui/<theme>`` directory to be overwritten.  The default is not to overwrite theme files.', ['--overwrite-theme-files'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Keep existing theme files in the ``ui/<theme>`` directory; do not overwrite any.  This is the default.', ['--keep-theme-files'], {'action': 'store_false', 'dest': 'overwrite_theme_files'}), ('Set the initial view mode to "slideshow" [default] or "outline".', ['--view-mode'], {'choices': ['slideshow', 'outline'], 'default': 'slideshow', 'metavar': '<mode>'}), ('Normally hide the presentation controls in slideshow mode. This is the default.', ['--hidden-controls'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Always show the presentation controls in slideshow mode.  The default is to hide the controls.', ['--visible-controls'], {'action': 'store_false', 'dest': 'hidden_controls'}), ('Enable the current slide indicator ("1 / 15").  The default is to disable it.', ['--current-slide'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Disable the current slide indicator.  This is the default.', ['--no-current-slide'], {'action': 'store_false', 'dest': 'current_slide'})))

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 = {'toc_backlinks': 0}

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

config_section = 's5_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.

class S5HTMLTranslator(*args)

Bases: HTMLTranslator

s5_stylesheet_template = '<!-- configuration parameters -->\n<meta name="defaultView" content="%(view_mode)s" />\n<meta name="controlVis" content="%(control_visibility)s" />\n<!-- style sheet links -->\n<script src="%(path)s/slides.js" type="text/javascript"></script>\n<link rel="stylesheet" href="%(path)s/slides.css"\n      type="text/css" media="projection" id="slideProj" />\n<link rel="stylesheet" href="%(path)s/outline.css"\n      type="text/css" media="screen" id="outlineStyle" />\n<link rel="stylesheet" href="%(path)s/print.css"\n      type="text/css" media="print" id="slidePrint" />\n<link rel="stylesheet" href="%(path)s/opera.css"\n      type="text/css" media="projection" id="operaFix" />\n'

disable_current_slide = '\n<style type="text/css">\n#currentSlide {display: none;}\n</style>\n'

layout_template = '<div class="layout">\n<div id="controls"></div>\n<div id="currentSlide"></div>\n<div id="header">\n%(header)s\n</div>\n<div id="footer">\n%(title)s%(footer)s\n</div>\n</div>\n'

default_theme = 'default'

Name of the default theme.

base_theme_file = '__base__'

Name of the file containing the name of the base theme.

direct_theme_files = ('slides.css', 'outline.css', 'print.css', 'opera.css', 'slides.js')

Names of theme files directly linked to in the output HTML

indirect_theme_files = ('s5-core.css', 'framing.css', 'pretty.css')

Names of files used indirectly; imported or used by files in direct_theme_files.

required_theme_files = ('s5-core.css', 'framing.css', 'pretty.css', 'slides.css', 'outline.css', 'print.css', 'opera.css', 'slides.js')

Names of mandatory theme files.

setup_theme()

copy_theme()

Locate & copy theme files.

A theme may be explicitly based on another theme via a ‘__base__’ file. The default base theme is ‘default’. Files are accumulated from the specified theme, any base themes, and ‘default’.

files_to_skip_pattern = re.compile('~$|\\.bak$|#$|\\.cvsignore$')

copy_file(name, source_dir, dest_dir)

Copy file name from source_dir to dest_dir. Return 1 if the file exists in either source_dir or dest_dir.

depart_document(node)

depart_footer(node)

depart_header(node)

visit_section(node)

visit_subtitle(node)

visit_title(node)