{self.encode(title)}

) documenttag_args = {'tagname': 'div', 'CLASS': 'document'} # Template for the MathJax script in the header: mathjax_script = '\n' mathjax_url = 'file:/usr/share/javascript/mathjax/MathJax.js' """ URL of the MathJax javascript library. The MathJax library ought to be installed on the same server as the rest of the deployed site files and specified in the `math-output` setting appended to "mathjax". See `Docutils Configuration`__. __ https://docutils.sourceforge.io/docs/user/config.html#math-output The fallback tries a local MathJax installation at ``/usr/share/javascript/mathjax/MathJax.js``. """ stylesheet_link = '\n' embedded_stylesheet = '\n' words_and_spaces = re.compile(r'[^ \n]+| +|\n') # wrap point inside word: in_word_wrap_point = re.compile(r'.+\W\W.+|[-?].+') lang_attribute = 'lang' # name changes to 'xml:lang' in XHTML 1.1 special_characters = {ord('&'): '&', ord('<'): '<', ord('"'): '"', ord('>'): '>', ord('@'): '@', # may thwart address harvesters } """Character references for characters with a special meaning in HTML.""" videotypes = ('video/mp4', 'video/webm', 'video/ogg') """MIME types supported by the HTML5

{suffix}') elif mimetype == 'application/x-shockwave-flash': atts['type'] = mimetype element = (self.starttag(node, 'object', '', data=uri, **atts) + f'{alt}{suffix}') elif element: # embedded SVG, see above element += suffix else: atts['alt'] = alt element = self.emptytag(node, 'img', suffix, src=uri, **atts) self.body.append(element) if suffix: # block-element self.report_messages(node) def depart_image(self, node) -> None: pass def visit_inline(self, node) -> None: self.body.append(self.starttag(node, 'span', '')) def depart_inline(self, node) -> None: self.body.append('') # footnote and citation labels: def visit_label(self, node) -> None: self.body.append('') self.body.append('[') # footnote/citation backrefs: if self.settings.footnote_backlinks: backrefs = node.parent.get('backrefs', []) if len(backrefs) == 1: self.body.append('' % backrefs[0]) def depart_label(self, node) -> None: backrefs = [] if self.settings.footnote_backlinks: backrefs = node.parent.get('backrefs', backrefs) if len(backrefs) == 1: self.body.append('') self.body.append(']\n') if len(backrefs) > 1: backlinks = ['%s' % (ref, i) for (i, ref) in enumerate(backrefs, 1)] self.body.append('(%s)\n' % ','.join(backlinks)) def visit_legend(self, node) -> None: self.body.append(self.starttag(node, 'div', CLASS='legend')) def depart_legend(self, node) -> None: self.body.append('\n') def visit_line(self, node) -> None: self.body.append(self.starttag(node, 'div', suffix='', CLASS='line')) if not len(node): self.body.append('
') def depart_line(self, node) -> None: self.body.append('\n') def visit_line_block(self, node) -> None: self.body.append(self.starttag(node, 'div', CLASS='line-block')) def depart_line_block(self, node) -> None: self.body.append('\n') def visit_list_item(self, node) -> None: self.body.append(self.starttag(node, 'li', '')) def depart_list_item(self, node) -> None: self.body.append('\n') # inline literal def visit_literal(self, node): # special case: "code" role classes = node['classes'] if 'code' in classes: # filter 'code' from class arguments classes.pop(classes.index('code')) self.body.append(self.starttag(node, 'code', '')) return self.body.append( self.starttag(node, 'span', '', CLASS='docutils literal')) text = node.astext() if not isinstance(node.parent, nodes.literal_block): text = text.replace('\n', ' ') # Protect text like ``--an-option`` and the regular expression # ``[+]?(\d+(\.\d*)?|\.\d+)`` from bad line wrapping for token in self.words_and_spaces.findall(text): if token.strip() and self.in_word_wrap_point.search(token): self.body.append('%s' % self.encode(token)) else: self.body.append(self.encode(token)) self.body.append('') raise nodes.SkipNode # content already processed def depart_literal(self, node) -> None: # skipped unless literal element is from "code" role: self.body.append('') def visit_literal_block(self, node) -> None: self.body.append(self.starttag(node, 'pre', '', CLASS='literal-block')) if 'code' in node['classes']: self.body.append('

')

    def depart_literal_block(self, node) -> None:
        if 'code' in node['classes']:
            self.body.append('

') self.body.append('\n') # Mathematics: # As there is no native HTML math support, we provide alternatives # for the math-output: LaTeX and MathJax simply wrap the content, # HTML and MathML also convert the math_code. # HTML element: math_tags = { # format: (inline, block, [class arguments]) 'html': ('span', 'div', ['formula']), 'latex': ('tt', 'pre', ['math']), 'mathjax': ('span', 'div', ['math']), 'mathml': ('', 'div', []), 'problematic': ('span', 'pre', ['math', 'problematic']), } def visit_math(self, node): # Also called from `visit_math_block()`: is_block = isinstance(node, nodes.math_block) format = self.math_output math_code = node.astext().translate(unichar2tex.uni2tex_table) # preamble code and conversion if format == 'html': if self.math_options and not self.math_header: self.math_header = [ self.stylesheet_call(utils.find_file_in_dirs( s, self.settings.stylesheet_dirs), adjust_path=True) for s in self.math_options.split(',')] math2html.DocumentParameters.displaymode = is_block # TODO: fix display mode in matrices and fractions math_code = wrap_math_code(math_code, is_block) math_code = math2html.math2html(math_code) elif format == 'latex': math_code = self.encode(math_code) elif format == 'mathjax': if not self.math_header: if self.math_options: self.mathjax_url = self.math_options else: self.document.reporter.warning( 'No MathJax URL specified, using local fallback ' '(see config.html).', base_node=node) # append MathJax configuration # (input LaTeX with AMS, output common HTML): if '?' not in self.mathjax_url: self.mathjax_url += '?config=TeX-AMS_CHTML' self.math_header = [self.mathjax_script % self.mathjax_url] if is_block: math_code = wrap_math_code(math_code, is_block) else: math_code = rf'\({math_code}\)' math_code = self.encode(math_code) elif format == 'mathml': if 'XHTML 1' in self.doctype: self.content_type = self.content_type_mathml if self.math_options: converter = getattr(tex2mathml_extern, self.math_options) else: converter = latex2mathml.tex2mathml try: math_code = converter(math_code, as_block=is_block) except (MathError, OSError) as err: details = getattr(err, 'details', []) self.messages.append(self.document.reporter.warning( err, *details, base_node=node)) math_code = self.encode(node.astext()) if self.settings.report_level <= 2: format = 'problematic' else: format = 'latex' if isinstance(err, OSError): # report missing converter only once self.math_output = format # append to document body tag = self.math_tags[format][is_block] suffix = '\n' if is_block else '' if tag: self.body.append(self.starttag(node, tag, suffix=suffix, classes=self.math_tags[format][2])) self.body.extend([math_code, suffix]) if tag: self.body.append(f'{suffix}') # Content already processed: raise nodes.SkipChildren def depart_math(self, node) -> None: pass def visit_math_block(self, node) -> None: self.visit_math(node) def depart_math_block(self, node) -> None: self.report_messages(node) # Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1 # HTML5/polyglot recommends using both def visit_meta(self, node) -> None: self.meta.append(self.emptytag(node, 'meta', **node.non_default_attributes())) def depart_meta(self, node) -> None: pass def visit_option(self, node) -> None: self.body.append(self.starttag(node, 'span', '', CLASS='option')) def depart_option(self, node) -> None: self.body.append('') if isinstance(node.next_node(descend=False, siblings=True), nodes.option): self.body.append(', ') def visit_option_argument(self, node) -> None: self.body.append(node.get('delimiter', ' ')) self.body.append(self.starttag(node, 'var', '')) def depart_option_argument(self, node) -> None: self.body.append('') def visit_option_group(self, node) -> None: self.body.append(self.starttag(node, 'dt', '')) self.body.append('') def depart_option_group(self, node) -> None: self.body.append('\n') def visit_option_list(self, node) -> None: self.body.append( self.starttag(node, 'dl', CLASS='option-list')) def depart_option_list(self, node) -> None: self.body.append('\n') def visit_option_list_item(self, node) -> None: pass def depart_option_list_item(self, node) -> None: pass def visit_option_string(self, node) -> None: pass def depart_option_string(self, node) -> None: pass def visit_organization(self, node) -> None: self.visit_docinfo_item(node, 'organization') def depart_organization(self, node) -> None: self.depart_docinfo_item() # Do not omit

tags # -------------------- # # The HTML4CSS1 writer does this to "produce # visually compact lists (less vertical whitespace)". This writer # relies on CSS rules for visual compactness. # # * In XHTML 1.1, e.g., a

element may not contain # character data, so you cannot drop the
tags. # * Keeping simple paragraphs in the field_body enables a CSS # rule to start the field-body on a new line if the label is too long # * it makes the code simpler. # # TODO: omit paragraph tags in simple table cells? def visit_paragraph(self, node) -> None: self.body.append(self.starttag(node, 'p', '')) def depart_paragraph(self, node) -> None: self.body.append('
') if not (isinstance(node.parent, (nodes.list_item, nodes.entry)) and (len(node.parent) == 1)): self.body.append('\n') self.report_messages(node) def visit_problematic(self, node) -> None: if node.hasattr('refid'): self.body.append('' % node['refid']) self.context.append('') else: self.context.append('') self.body.append(self.starttag(node, 'span', '', CLASS='problematic')) def depart_problematic(self, node) -> None: self.body.append('') self.body.append(self.context.pop()) def visit_raw(self, node): if 'html' in node.get('format', '').split(): if isinstance(node.parent, nodes.TextElement): tagname = 'span' else: tagname = 'div' if node['classes']: self.body.append(self.starttag(node, tagname, suffix='')) self.body.append(node.astext()) if node['classes']: self.body.append('' % tagname) # Keep non-HTML raw text out of output: raise nodes.SkipNode def visit_reference(self, node) -> None: atts = {'classes': ['reference']} suffix = '' if 'refuri' in node: atts['href'] = node['refuri'] if (self.settings.cloak_email_addresses and atts['href'].startswith('mailto:')): atts['href'] = self.cloak_mailto(atts['href']) self.in_mailto = True atts['classes'].append('external') else: assert 'refid' in node, \ 'References must have "refuri" or "refid" attribute.' atts['href'] = '#' + node['refid'] atts['classes'].append('internal') if len(node) == 1 and isinstance(node[0], nodes.image): atts['classes'].append('image-reference') if not isinstance(node.parent, nodes.TextElement): suffix = '\n' self.body.append(self.starttag(node, 'a', suffix, **atts)) def depart_reference(self, node) -> None: self.body.append('') if not isinstance(node.parent, nodes.TextElement): self.body.append('\n') self.in_mailto = False def visit_revision(self, node) -> None: self.visit_docinfo_item(node, 'revision', meta=False) def depart_revision(self, node) -> None: self.depart_docinfo_item() def visit_row(self, node) -> None: self.body.append(self.starttag(node, 'tr', '')) node.column = 0 def depart_row(self, node) -> None: self.body.append('\n') def visit_rubric(self, node) -> None: self.body.append(self.starttag(node, 'p', '', CLASS='rubric')) def depart_rubric(self, node) -> None: self.body.append('
\n') def visit_section(self, node) -> None: self.section_level += 1 self.body.append( self.starttag(node, 'div', CLASS='section')) def depart_section(self, node) -> None: self.section_level -= 1 self.body.append('\n') # TODO: use the new HTML5 element
def visit_sidebar(self, node) -> None: self.body.append( self.starttag(node, 'div', CLASS='sidebar')) self.in_sidebar = True def depart_sidebar(self, node) -> None: self.body.append('\n') self.in_sidebar = False def visit_status(self, node) -> None: self.visit_docinfo_item(node, 'status', meta=False) def depart_status(self, node) -> None: self.depart_docinfo_item() def visit_strong(self, node) -> None: self.body.append(self.starttag(node, 'strong', '')) def depart_strong(self, node) -> None: self.body.append('') def visit_subscript(self, node) -> None: self.body.append(self.starttag(node, 'sub', '')) def depart_subscript(self, node) -> None: self.body.append('') def visit_substitution_definition(self, node): """Internal only.""" raise nodes.SkipNode def visit_substitution_reference(self, node) -> None: self.unimplemented_visit(node) # h1–h6 elements must not be used to markup subheadings, subtitles, # alternative titles and taglines unless intended to be the heading for a # new section or subsection. # -- http://www.w3.org/TR/html51/sections.html#headings-and-sections def visit_subtitle(self, node) -> None: if isinstance(node.parent, nodes.sidebar): classes = ['sidebar-subtitle'] elif isinstance(node.parent, nodes.document): classes = ['subtitle'] self.in_document_title = len(self.body) + 1 elif isinstance(node.parent, nodes.section): classes = ['section-subtitle'] self.body.append(self.starttag(node, 'p', '', classes=classes)) def depart_subtitle(self, node) -> None: self.body.append('
\n') if isinstance(node.parent, nodes.document): self.subtitle = self.body[self.in_document_title:-1] self.in_document_title = 0 self.body_pre_docinfo.extend(self.body) self.html_subtitle.extend(self.body) del self.body[:] def visit_superscript(self, node) -> None: self.body.append(self.starttag(node, 'sup', '')) def depart_superscript(self, node) -> None: self.body.append('') def visit_system_message(self, node) -> None: self.body.append(self.starttag(node, 'aside', CLASS='system-message')) self.body.append('
') backref_text = '' if len(node['backrefs']): backrefs = node['backrefs'] if len(backrefs) == 1: backref_text = ('; backlink' % backrefs[0]) else: i = 1 backlinks = [] for backref in backrefs: backlinks.append('%s' % (backref, i)) i += 1 backref_text = ('; backlinks: %s' % ', '.join(backlinks)) if node.hasattr('line'): line = ', line %s' % node['line'] else: line = '' self.body.append('System Message: %s/%s ' '(%s%s)%s
\n' % (node['type'], node['level'], self.encode(node['source']), line, backref_text)) def depart_system_message(self, node) -> None: self.body.append('
\n') def visit_table(self, node) -> None: atts = {'classes': self.settings.table_style.replace(',', ' ').split()} if 'align' in node: atts['classes'].append('align-%s' % node['align']) if 'width' in node: width = node['width'] if width[-1:] in '0123456789.': # unitless value width += 'px' # add default length unit atts['style'] = f'width: {width};' tag = self.starttag(node, 'table', **atts) self.body.append(tag) def depart_table(self, node) -> None: self.body.append('\n') self.report_messages(node) def visit_target(self, node) -> None: if ('refuri' not in node and 'refid' not in node and 'refname' not in node): self.body.append(self.starttag(node, 'span', '', CLASS='target')) self.context.append('') else: self.context.append('') def depart_target(self, node) -> None: self.body.append(self.context.pop()) # no hard-coded vertical alignment in table body def visit_tbody(self, node) -> None: self.body.append(self.starttag(node, 'tbody')) def depart_tbody(self, node) -> None: self.body.append('\n') def visit_term(self, node) -> None: if 'details' in node.parent.parent['classes']: self.body.append(self.starttag(node, 'summary', suffix='')) else: # The parent node (definition_list_item) is omitted in HTML. self.body.append(self.starttag(node, 'dt', suffix='', classes=node.parent['classes'], ids=node.parent['ids'])) def depart_term(self, node) -> None: # Nest (optional) classifier(s) in the
element if node.next_node(nodes.classifier, descend=False, siblings=True): return # skip (depart_classifier() calls this function again) if 'details' in node.parent.parent['classes']: self.body.append('\n') else: self.body.append('
\n') def visit_tgroup(self, node) -> None: self.colspecs = [] node.stubs = [] def depart_tgroup(self, node) -> None: pass def visit_thead(self, node) -> None: self.body.append(self.starttag(node, 'thead')) def depart_thead(self, node) -> None: self.body.append('\n') def section_title_tags(self, node): atts = {} h_level = self.section_level + self.initial_header_level - 1 # Only 6 heading levels have dedicated HTML tags. tagname = 'h%i' % min(h_level, 6) if h_level > 6: atts['aria-level'] = h_level start_tag = self.starttag(node, tagname, '', **atts) if node.hasattr('refid'): atts = {} atts['class'] = 'toc-backref' atts['role'] = 'doc-backlink' # HTML5 only atts['href'] = '#' + node['refid'] start_tag += self.starttag(nodes.reference(), 'a', '', **atts) close_tag = '\n' % tagname else: close_tag = '\n' % tagname return start_tag, close_tag def visit_title(self, node) -> None: close_tag = '
\n' if isinstance(node.parent, nodes.topic): # TODO: use role="heading" or
? (HTML5 only) self.body.append( self.starttag(node, 'p', '', CLASS='topic-title')) if (self.settings.toc_backlinks and 'contents' in node.parent['classes']): self.body.append('') close_tag = '
\n' elif isinstance(node.parent, nodes.sidebar): # TODO: use role="heading" or
? (HTML5 only) self.body.append( self.starttag(node, 'p', '', CLASS='sidebar-title')) elif isinstance(node.parent, nodes.Admonition): self.body.append( self.starttag(node, 'p', '', CLASS='admonition-title')) elif isinstance(node.parent, nodes.table): self.body.append(self.starttag(node, 'caption', '')) close_tag = '\n' elif isinstance(node.parent, nodes.document): self.body.append(self.starttag(node, 'h1', '', CLASS='title')) close_tag = '
\n' self.in_document_title = len(self.body) else: assert isinstance(node.parent, nodes.section) # Get correct heading and evt. backlink tags start_tag, close_tag = self.section_title_tags(node) self.body.append(start_tag) self.context.append(close_tag) def depart_title(self, node) -> None: self.body.append(self.context.pop()) if self.in_document_title: self.title = self.body[self.in_document_title:-1] self.in_document_title = 0 self.body_pre_docinfo.extend(self.body) self.html_title.extend(self.body) del self.body[:] def visit_title_reference(self, node) -> None: self.body.append(self.starttag(node, 'cite', '')) def depart_title_reference(self, node) -> None: self.body.append('') def visit_topic(self, node) -> None: self.body.append(self.starttag(node, 'div', CLASS='topic')) def depart_topic(self, node) -> None: self.body.append('\n') def visit_transition(self, node) -> None: self.body.append(self.emptytag(node, 'hr', CLASS='docutils')) def depart_transition(self, node) -> None: pass def visit_version(self, node) -> None: self.visit_docinfo_item(node, 'version', meta=False) def depart_version(self, node) -> None: self.depart_docinfo_item() def unimplemented_visit(self, node): raise NotImplementedError('visiting unimplemented node type: %s' % node.__class__.__name__) class SimpleListChecker(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. This version also checks for simple field lists and docinfo. """ def default_visit(self, node): raise nodes.NodeFound def default_departure(self, node): pass def visit_list_item(self, node): children = [child for child in node.children if not isinstance(child, nodes.Invisible)] if (children and isinstance(children[0], nodes.paragraph) and (isinstance(children[-1], nodes.bullet_list) or isinstance(children[-1], nodes.enumerated_list) or isinstance(children[-1], nodes.field_list))): children.pop() if len(children) <= 1: return else: raise nodes.NodeFound def pass_node(self, node) -> None: pass def ignore_node(self, node): # ignore nodes that are never complex (can contain only inline nodes) raise nodes.SkipNode # Paragraphs and text visit_Text = ignore_node visit_paragraph = ignore_node # Lists visit_bullet_list = pass_node visit_enumerated_list = pass_node visit_docinfo = pass_node # Docinfo nodes: visit_author = ignore_node visit_authors = visit_list_item visit_address = visit_list_item visit_contact = pass_node visit_copyright = ignore_node visit_date = ignore_node visit_organization = ignore_node visit_status = ignore_node visit_version = visit_list_item # Definition list: visit_definition_list = pass_node visit_definition_list_item = pass_node visit_term = ignore_node visit_classifier = pass_node visit_definition = visit_list_item # Field list: visit_field_list = pass_node visit_field = pass_node # the field body corresponds to a list item visit_field_body = visit_list_item visit_field_name = ignore_node # Invisible nodes should be ignored. visit_comment = ignore_node visit_substitution_definition = ignore_node visit_target = ignore_node visit_pending = ignore_node

? (HTML5 only) self.body.append( self.starttag(node, 'p', '', CLASS='topic-title')) if (self.settings.toc_backlinks and 'contents' in node.parent['classes']): self.body.append('') close_tag = '\n' elif isinstance(node.parent, nodes.sidebar): # TODO: use role="heading" or

? (HTML5 only) self.body.append( self.starttag(node, 'p', '', CLASS='topic-title')) if (self.settings.toc_backlinks and 'contents' in node.parent['classes']): self.body.append('') close_tag = '
\n' elif isinstance(node.parent, nodes.sidebar): # TODO: use role="heading" or