937 lines
36 KiB
Python
937 lines
36 KiB
Python
"""Experimental docutils writers for HTML5 handling Sphinx's custom nodes."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
import posixpath
|
|
import re
|
|
import urllib.parse
|
|
from collections.abc import Iterable
|
|
from typing import TYPE_CHECKING, cast
|
|
|
|
from docutils import nodes
|
|
from docutils.writers.html5_polyglot import HTMLTranslator as BaseTranslator
|
|
|
|
from sphinx import addnodes
|
|
from sphinx.locale import _, __, admonitionlabels
|
|
from sphinx.util import logging
|
|
from sphinx.util.docutils import SphinxTranslator
|
|
from sphinx.util.images import get_image_size
|
|
|
|
if TYPE_CHECKING:
|
|
from docutils.nodes import Element, Node, Text
|
|
|
|
from sphinx.builders import Builder
|
|
from sphinx.builders.html import StandaloneHTMLBuilder
|
|
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
# A good overview of the purpose behind these classes can be found here:
|
|
# http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html
|
|
|
|
|
|
def multiply_length(length: str, scale: int) -> str:
|
|
"""Multiply *length* (width or height) by *scale*."""
|
|
matched = re.match(r'^(\d*\.?\d*)\s*(\S*)$', length)
|
|
if not matched:
|
|
return length
|
|
if scale == 100:
|
|
return length
|
|
amount, unit = matched.groups()
|
|
result = float(amount) * scale / 100
|
|
return f"{int(result)}{unit}"
|
|
|
|
|
|
class HTML5Translator(SphinxTranslator, BaseTranslator):
|
|
"""
|
|
Our custom HTML translator.
|
|
"""
|
|
|
|
builder: StandaloneHTMLBuilder
|
|
# Override docutils.writers.html5_polyglot:HTMLTranslator
|
|
# otherwise, nodes like <inline classes="s">...</inline> will be
|
|
# converted to <s>...</s> by `visit_inline`.
|
|
supported_inline_tags: set[str] = set()
|
|
|
|
def __init__(self, document: nodes.document, builder: Builder) -> None:
|
|
super().__init__(document, builder)
|
|
|
|
self.highlighter = self.builder.highlighter
|
|
self.docnames = [self.builder.current_docname] # for singlehtml builder
|
|
self.manpages_url = self.config.manpages_url
|
|
self.protect_literal_text = 0
|
|
self.secnumber_suffix = self.config.html_secnumber_suffix
|
|
self.param_separator = ''
|
|
self.optional_param_level = 0
|
|
self._table_row_indices = [0]
|
|
self._fieldlist_row_indices = [0]
|
|
self.required_params_left = 0
|
|
|
|
def visit_start_of_file(self, node: Element) -> None:
|
|
# only occurs in the single-file builder
|
|
self.docnames.append(node['docname'])
|
|
self.body.append('<span id="document-%s"></span>' % node['docname'])
|
|
|
|
def depart_start_of_file(self, node: Element) -> None:
|
|
self.docnames.pop()
|
|
|
|
#############################################################
|
|
# Domain-specific object descriptions
|
|
#############################################################
|
|
|
|
# Top-level nodes for descriptions
|
|
##################################
|
|
|
|
def visit_desc(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'dl'))
|
|
|
|
def depart_desc(self, node: Element) -> None:
|
|
self.body.append('</dl>\n\n')
|
|
|
|
def visit_desc_signature(self, node: Element) -> None:
|
|
# the id is set automatically
|
|
self.body.append(self.starttag(node, 'dt'))
|
|
self.protect_literal_text += 1
|
|
|
|
def depart_desc_signature(self, node: Element) -> None:
|
|
self.protect_literal_text -= 1
|
|
if not node.get('is_multiline'):
|
|
self.add_permalink_ref(node, _('Link to this definition'))
|
|
self.body.append('</dt>\n')
|
|
|
|
def visit_desc_signature_line(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_desc_signature_line(self, node: Element) -> None:
|
|
if node.get('add_permalink'):
|
|
# the permalink info is on the parent desc_signature node
|
|
self.add_permalink_ref(node.parent, _('Link to this definition'))
|
|
self.body.append('<br />')
|
|
|
|
def visit_desc_content(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'dd', ''))
|
|
|
|
def depart_desc_content(self, node: Element) -> None:
|
|
self.body.append('</dd>')
|
|
|
|
def visit_desc_inline(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'span', ''))
|
|
|
|
def depart_desc_inline(self, node: Element) -> None:
|
|
self.body.append('</span>')
|
|
|
|
# Nodes for high-level structure in signatures
|
|
##############################################
|
|
|
|
def visit_desc_name(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'span', ''))
|
|
|
|
def depart_desc_name(self, node: Element) -> None:
|
|
self.body.append('</span>')
|
|
|
|
def visit_desc_addname(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'span', ''))
|
|
|
|
def depart_desc_addname(self, node: Element) -> None:
|
|
self.body.append('</span>')
|
|
|
|
def visit_desc_type(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_desc_type(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_desc_returns(self, node: Element) -> None:
|
|
self.body.append(' <span class="sig-return">')
|
|
self.body.append('<span class="sig-return-icon">→</span>')
|
|
self.body.append(' <span class="sig-return-typehint">')
|
|
|
|
def depart_desc_returns(self, node: Element) -> None:
|
|
self.body.append('</span></span>')
|
|
|
|
def _visit_sig_parameter_list(
|
|
self,
|
|
node: Element,
|
|
parameter_group: type[Element],
|
|
sig_open_paren: str,
|
|
sig_close_paren: str,
|
|
) -> None:
|
|
"""Visit a signature parameters or type parameters list.
|
|
|
|
The *parameter_group* value is the type of child nodes acting as required parameters
|
|
or as a set of contiguous optional parameters.
|
|
"""
|
|
self.body.append(f'<span class="sig-paren">{sig_open_paren}</span>')
|
|
self.is_first_param = True
|
|
self.optional_param_level = 0
|
|
self.params_left_at_level = 0
|
|
self.param_group_index = 0
|
|
# Counts as what we call a parameter group either a required parameter, or a
|
|
# set of contiguous optional ones.
|
|
self.list_is_required_param = [isinstance(c, parameter_group) for c in node.children]
|
|
# How many required parameters are left.
|
|
self.required_params_left = sum(self.list_is_required_param)
|
|
self.param_separator = node.child_text_separator
|
|
self.multi_line_parameter_list = node.get('multi_line_parameter_list', False)
|
|
if self.multi_line_parameter_list:
|
|
self.body.append('\n\n')
|
|
self.body.append(self.starttag(node, 'dl'))
|
|
self.param_separator = self.param_separator.rstrip()
|
|
self.context.append(sig_close_paren)
|
|
|
|
def _depart_sig_parameter_list(self, node: Element) -> None:
|
|
if node.get('multi_line_parameter_list'):
|
|
self.body.append('</dl>\n\n')
|
|
sig_close_paren = self.context.pop()
|
|
self.body.append(f'<span class="sig-paren">{sig_close_paren}</span>')
|
|
|
|
def visit_desc_parameterlist(self, node: Element) -> None:
|
|
self._visit_sig_parameter_list(node, addnodes.desc_parameter, '(', ')')
|
|
|
|
def depart_desc_parameterlist(self, node: Element) -> None:
|
|
self._depart_sig_parameter_list(node)
|
|
|
|
def visit_desc_type_parameter_list(self, node: Element) -> None:
|
|
self._visit_sig_parameter_list(node, addnodes.desc_type_parameter, '[', ']')
|
|
|
|
def depart_desc_type_parameter_list(self, node: Element) -> None:
|
|
self._depart_sig_parameter_list(node)
|
|
|
|
# If required parameters are still to come, then put the comma after
|
|
# the parameter. Otherwise, put the comma before. This ensures that
|
|
# signatures like the following render correctly (see issue #1001):
|
|
#
|
|
# foo([a, ]b, c[, d])
|
|
#
|
|
def visit_desc_parameter(self, node: Element) -> None:
|
|
on_separate_line = self.multi_line_parameter_list
|
|
if on_separate_line and not (self.is_first_param and self.optional_param_level > 0):
|
|
self.body.append(self.starttag(node, 'dd', ''))
|
|
if self.is_first_param:
|
|
self.is_first_param = False
|
|
elif not on_separate_line and not self.required_params_left:
|
|
self.body.append(self.param_separator)
|
|
if self.optional_param_level == 0:
|
|
self.required_params_left -= 1
|
|
else:
|
|
self.params_left_at_level -= 1
|
|
if not node.hasattr('noemph'):
|
|
self.body.append('<em class="sig-param">')
|
|
|
|
def depart_desc_parameter(self, node: Element) -> None:
|
|
if not node.hasattr('noemph'):
|
|
self.body.append('</em>')
|
|
is_required = self.list_is_required_param[self.param_group_index]
|
|
if self.multi_line_parameter_list:
|
|
is_last_group = self.param_group_index + 1 == len(self.list_is_required_param)
|
|
next_is_required = (
|
|
not is_last_group
|
|
and self.list_is_required_param[self.param_group_index + 1]
|
|
)
|
|
opt_param_left_at_level = self.params_left_at_level > 0
|
|
if opt_param_left_at_level or is_required and (is_last_group or next_is_required):
|
|
self.body.append(self.param_separator)
|
|
self.body.append('</dd>\n')
|
|
|
|
elif self.required_params_left:
|
|
self.body.append(self.param_separator)
|
|
|
|
if is_required:
|
|
self.param_group_index += 1
|
|
|
|
def visit_desc_type_parameter(self, node: Element) -> None:
|
|
self.visit_desc_parameter(node)
|
|
|
|
def depart_desc_type_parameter(self, node: Element) -> None:
|
|
self.depart_desc_parameter(node)
|
|
|
|
def visit_desc_optional(self, node: Element) -> None:
|
|
self.params_left_at_level = sum([isinstance(c, addnodes.desc_parameter)
|
|
for c in node.children])
|
|
self.optional_param_level += 1
|
|
self.max_optional_param_level = self.optional_param_level
|
|
if self.multi_line_parameter_list:
|
|
# If the first parameter is optional, start a new line and open the bracket.
|
|
if self.is_first_param:
|
|
self.body.append(self.starttag(node, 'dd', ''))
|
|
self.body.append('<span class="optional">[</span>')
|
|
# Else, if there remains at least one required parameter, append the
|
|
# parameter separator, open a new bracket, and end the line.
|
|
elif self.required_params_left:
|
|
self.body.append(self.param_separator)
|
|
self.body.append('<span class="optional">[</span>')
|
|
self.body.append('</dd>\n')
|
|
# Else, open a new bracket, append the parameter separator,
|
|
# and end the line.
|
|
else:
|
|
self.body.append('<span class="optional">[</span>')
|
|
self.body.append(self.param_separator)
|
|
self.body.append('</dd>\n')
|
|
else:
|
|
self.body.append('<span class="optional">[</span>')
|
|
|
|
def depart_desc_optional(self, node: Element) -> None:
|
|
self.optional_param_level -= 1
|
|
if self.multi_line_parameter_list:
|
|
# If it's the first time we go down one level, add the separator
|
|
# before the bracket.
|
|
if self.optional_param_level == self.max_optional_param_level - 1:
|
|
self.body.append(self.param_separator)
|
|
self.body.append('<span class="optional">]</span>')
|
|
# End the line if we have just closed the last bracket of this
|
|
# optional parameter group.
|
|
if self.optional_param_level == 0:
|
|
self.body.append('</dd>\n')
|
|
else:
|
|
self.body.append('<span class="optional">]</span>')
|
|
if self.optional_param_level == 0:
|
|
self.param_group_index += 1
|
|
|
|
def visit_desc_annotation(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'em', '', CLASS='property'))
|
|
|
|
def depart_desc_annotation(self, node: Element) -> None:
|
|
self.body.append('</em>')
|
|
|
|
##############################################
|
|
|
|
def visit_versionmodified(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'div', CLASS=node['type']))
|
|
|
|
def depart_versionmodified(self, node: Element) -> None:
|
|
self.body.append('</div>\n')
|
|
|
|
# overwritten
|
|
def visit_reference(self, node: Element) -> None:
|
|
atts = {'class': 'reference'}
|
|
if node.get('internal') or 'refuri' not in node:
|
|
atts['class'] += ' internal'
|
|
else:
|
|
atts['class'] += ' external'
|
|
if 'refuri' in node:
|
|
atts['href'] = node['refuri'] or '#'
|
|
if self.settings.cloak_email_addresses and atts['href'].startswith('mailto:'):
|
|
atts['href'] = self.cloak_mailto(atts['href'])
|
|
self.in_mailto = True
|
|
else:
|
|
assert 'refid' in node, \
|
|
'References must have "refuri" or "refid" attribute.'
|
|
atts['href'] = '#' + node['refid']
|
|
if not isinstance(node.parent, nodes.TextElement):
|
|
assert len(node) == 1 and isinstance(node[0], nodes.image) # NoQA: PT018
|
|
atts['class'] += ' image-reference'
|
|
if 'reftitle' in node:
|
|
atts['title'] = node['reftitle']
|
|
if 'target' in node:
|
|
atts['target'] = node['target']
|
|
self.body.append(self.starttag(node, 'a', '', **atts))
|
|
|
|
if node.get('secnumber'):
|
|
self.body.append(('%s' + self.secnumber_suffix) %
|
|
'.'.join(map(str, node['secnumber'])))
|
|
|
|
def visit_number_reference(self, node: Element) -> None:
|
|
self.visit_reference(node)
|
|
|
|
def depart_number_reference(self, node: Element) -> None:
|
|
self.depart_reference(node)
|
|
|
|
# overwritten -- we don't want source comments to show up in the HTML
|
|
def visit_comment(self, node: Element) -> None: # type: ignore[override]
|
|
raise nodes.SkipNode
|
|
|
|
# overwritten
|
|
def visit_admonition(self, node: Element, name: str = '') -> None:
|
|
self.body.append(self.starttag(
|
|
node, 'div', CLASS=('admonition ' + name)))
|
|
if name:
|
|
node.insert(0, nodes.title(name, admonitionlabels[name]))
|
|
|
|
def depart_admonition(self, node: Element | None = None) -> None:
|
|
self.body.append('</div>\n')
|
|
|
|
def visit_seealso(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'seealso')
|
|
|
|
def depart_seealso(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def get_secnumber(self, node: Element) -> tuple[int, ...] | None:
|
|
if node.get('secnumber'):
|
|
return node['secnumber']
|
|
|
|
if isinstance(node.parent, nodes.section):
|
|
if self.builder.name == 'singlehtml':
|
|
docname = self.docnames[-1]
|
|
anchorname = "{}/#{}".format(docname, node.parent['ids'][0])
|
|
if anchorname not in self.builder.secnumbers:
|
|
anchorname = "%s/" % docname # try first heading which has no anchor
|
|
else:
|
|
anchorname = '#' + node.parent['ids'][0]
|
|
if anchorname not in self.builder.secnumbers:
|
|
anchorname = '' # try first heading which has no anchor
|
|
|
|
if self.builder.secnumbers.get(anchorname):
|
|
return self.builder.secnumbers[anchorname]
|
|
|
|
return None
|
|
|
|
def add_secnumber(self, node: Element) -> None:
|
|
secnumber = self.get_secnumber(node)
|
|
if secnumber:
|
|
self.body.append('<span class="section-number">%s</span>' %
|
|
('.'.join(map(str, secnumber)) + self.secnumber_suffix))
|
|
|
|
def add_fignumber(self, node: Element) -> None:
|
|
def append_fignumber(figtype: str, figure_id: str) -> None:
|
|
if self.builder.name == 'singlehtml':
|
|
key = f"{self.docnames[-1]}/{figtype}"
|
|
else:
|
|
key = figtype
|
|
|
|
if figure_id in self.builder.fignumbers.get(key, {}):
|
|
self.body.append('<span class="caption-number">')
|
|
prefix = self.config.numfig_format.get(figtype)
|
|
if prefix is None:
|
|
msg = __('numfig_format is not defined for %s') % figtype
|
|
logger.warning(msg)
|
|
else:
|
|
numbers = self.builder.fignumbers[key][figure_id]
|
|
self.body.append(prefix % '.'.join(map(str, numbers)) + ' ')
|
|
self.body.append('</span>')
|
|
|
|
figtype = self.builder.env.domains['std'].get_enumerable_node_type(node)
|
|
if figtype:
|
|
if len(node['ids']) == 0:
|
|
msg = __('Any IDs not assigned for %s node') % node.tagname
|
|
logger.warning(msg, location=node)
|
|
else:
|
|
append_fignumber(figtype, node['ids'][0])
|
|
|
|
def add_permalink_ref(self, node: Element, title: str) -> None:
|
|
icon = self.config.html_permalinks_icon
|
|
if node['ids'] and self.config.html_permalinks and self.builder.add_permalinks:
|
|
self.body.append(
|
|
f'<a class="headerlink" href="#{node["ids"][0]}" title="{title}">{icon}</a>',
|
|
)
|
|
|
|
# overwritten
|
|
def visit_bullet_list(self, node: Element) -> None:
|
|
if len(node) == 1 and isinstance(node[0], addnodes.toctree):
|
|
# avoid emitting empty <ul></ul>
|
|
raise nodes.SkipNode
|
|
super().visit_bullet_list(node)
|
|
|
|
# overwritten
|
|
def visit_definition(self, node: Element) -> None:
|
|
# don't insert </dt> here.
|
|
self.body.append(self.starttag(node, 'dd', ''))
|
|
|
|
# overwritten
|
|
def depart_definition(self, node: Element) -> None:
|
|
self.body.append('</dd>\n')
|
|
|
|
# overwritten
|
|
def visit_classifier(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'span', '', CLASS='classifier'))
|
|
|
|
# overwritten
|
|
def depart_classifier(self, node: Element) -> None:
|
|
self.body.append('</span>')
|
|
|
|
next_node: Node = node.next_node(descend=False, siblings=True)
|
|
if not isinstance(next_node, nodes.classifier):
|
|
# close `<dt>` tag at the tail of classifiers
|
|
self.body.append('</dt>')
|
|
|
|
# overwritten
|
|
def visit_term(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'dt', ''))
|
|
|
|
# overwritten
|
|
def depart_term(self, node: Element) -> None:
|
|
next_node: Node = node.next_node(descend=False, siblings=True)
|
|
if isinstance(next_node, nodes.classifier):
|
|
# Leave the end tag to `self.depart_classifier()`, in case
|
|
# there's a classifier.
|
|
pass
|
|
else:
|
|
if isinstance(node.parent.parent.parent, addnodes.glossary):
|
|
# add permalink if glossary terms
|
|
self.add_permalink_ref(node, _('Link to this term'))
|
|
|
|
self.body.append('</dt>')
|
|
|
|
# overwritten
|
|
def visit_title(self, node: Element) -> None:
|
|
if isinstance(node.parent, addnodes.compact_paragraph) and node.parent.get('toctree'):
|
|
self.body.append(self.starttag(node, 'p', '', CLASS='caption', ROLE='heading'))
|
|
self.body.append('<span class="caption-text">')
|
|
self.context.append('</span></p>\n')
|
|
else:
|
|
super().visit_title(node)
|
|
self.add_secnumber(node)
|
|
self.add_fignumber(node.parent)
|
|
if isinstance(node.parent, nodes.table):
|
|
self.body.append('<span class="caption-text">')
|
|
|
|
def depart_title(self, node: Element) -> None:
|
|
close_tag = self.context[-1]
|
|
if (self.config.html_permalinks and self.builder.add_permalinks and
|
|
node.parent.hasattr('ids') and node.parent['ids']):
|
|
# add permalink anchor
|
|
if close_tag.startswith('</h'):
|
|
self.add_permalink_ref(node.parent, _('Link to this heading'))
|
|
elif close_tag.startswith('</a></h'):
|
|
self.body.append('</a><a class="headerlink" href="#%s" ' %
|
|
node.parent['ids'][0] +
|
|
'title="{}">{}'.format(
|
|
_('Link to this heading'),
|
|
self.config.html_permalinks_icon))
|
|
elif isinstance(node.parent, nodes.table):
|
|
self.body.append('</span>')
|
|
self.add_permalink_ref(node.parent, _('Link to this table'))
|
|
elif isinstance(node.parent, nodes.table):
|
|
self.body.append('</span>')
|
|
|
|
super().depart_title(node)
|
|
|
|
# overwritten
|
|
def visit_literal_block(self, node: Element) -> None:
|
|
if node.rawsource != node.astext():
|
|
# most probably a parsed-literal block -- don't highlight
|
|
return super().visit_literal_block(node)
|
|
|
|
lang = node.get('language', 'default')
|
|
linenos = node.get('linenos', False)
|
|
highlight_args = node.get('highlight_args', {})
|
|
highlight_args['force'] = node.get('force', False)
|
|
opts = self.config.highlight_options.get(lang, {})
|
|
|
|
if linenos and self.config.html_codeblock_linenos_style:
|
|
linenos = self.config.html_codeblock_linenos_style
|
|
|
|
highlighted = self.highlighter.highlight_block(
|
|
node.rawsource, lang, opts=opts, linenos=linenos,
|
|
location=node, **highlight_args,
|
|
)
|
|
starttag = self.starttag(node, 'div', suffix='',
|
|
CLASS='highlight-%s notranslate' % lang)
|
|
self.body.append(starttag + highlighted + '</div>\n')
|
|
raise nodes.SkipNode
|
|
|
|
def visit_caption(self, node: Element) -> None:
|
|
if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
|
|
self.body.append('<div class="code-block-caption">')
|
|
else:
|
|
super().visit_caption(node)
|
|
self.add_fignumber(node.parent)
|
|
self.body.append(self.starttag(node, 'span', '', CLASS='caption-text'))
|
|
|
|
def depart_caption(self, node: Element) -> None:
|
|
self.body.append('</span>')
|
|
|
|
# append permalink if available
|
|
if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
|
|
self.add_permalink_ref(node.parent, _('Link to this code'))
|
|
elif isinstance(node.parent, nodes.figure):
|
|
self.add_permalink_ref(node.parent, _('Link to this image'))
|
|
elif node.parent.get('toctree'):
|
|
self.add_permalink_ref(node.parent.parent, _('Link to this toctree'))
|
|
|
|
if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
|
|
self.body.append('</div>\n')
|
|
else:
|
|
super().depart_caption(node)
|
|
|
|
def visit_doctest_block(self, node: Element) -> None:
|
|
self.visit_literal_block(node)
|
|
|
|
# overwritten to add the <div> (for XHTML compliance)
|
|
def visit_block_quote(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'blockquote') + '<div>')
|
|
|
|
def depart_block_quote(self, node: Element) -> None:
|
|
self.body.append('</div></blockquote>\n')
|
|
|
|
# overwritten
|
|
def visit_literal(self, node: Element) -> None:
|
|
if 'kbd' in node['classes']:
|
|
self.body.append(self.starttag(node, 'kbd', '',
|
|
CLASS='docutils literal notranslate'))
|
|
return
|
|
lang = node.get("language", None)
|
|
if 'code' not in node['classes'] or not lang:
|
|
self.body.append(self.starttag(node, 'code', '',
|
|
CLASS='docutils literal notranslate'))
|
|
self.protect_literal_text += 1
|
|
return
|
|
|
|
opts = self.config.highlight_options.get(lang, {})
|
|
highlighted = self.highlighter.highlight_block(
|
|
node.astext(), lang, opts=opts, location=node, nowrap=True)
|
|
starttag = self.starttag(
|
|
node,
|
|
"code",
|
|
suffix="",
|
|
CLASS="docutils literal highlight highlight-%s" % lang,
|
|
)
|
|
self.body.append(starttag + highlighted.strip() + "</code>")
|
|
raise nodes.SkipNode
|
|
|
|
def depart_literal(self, node: Element) -> None:
|
|
if 'kbd' in node['classes']:
|
|
self.body.append('</kbd>')
|
|
else:
|
|
self.protect_literal_text -= 1
|
|
self.body.append('</code>')
|
|
|
|
def visit_productionlist(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'pre'))
|
|
names = []
|
|
productionlist = cast(Iterable[addnodes.production], node)
|
|
for production in productionlist:
|
|
names.append(production['tokenname'])
|
|
maxlen = max(len(name) for name in names)
|
|
lastname = None
|
|
for production in productionlist:
|
|
if production['tokenname']:
|
|
lastname = production['tokenname'].ljust(maxlen)
|
|
self.body.append(self.starttag(production, 'strong', ''))
|
|
self.body.append(lastname + '</strong> ::= ')
|
|
elif lastname is not None:
|
|
self.body.append('%s ' % (' ' * len(lastname)))
|
|
production.walkabout(self)
|
|
self.body.append('\n')
|
|
self.body.append('</pre>\n')
|
|
raise nodes.SkipNode
|
|
|
|
def depart_productionlist(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_production(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_production(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_centered(self, node: Element) -> None:
|
|
self.body.append(self.starttag(node, 'p', CLASS="centered") +
|
|
'<strong>')
|
|
|
|
def depart_centered(self, node: Element) -> None:
|
|
self.body.append('</strong></p>')
|
|
|
|
def visit_compact_paragraph(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_compact_paragraph(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_download_reference(self, node: Element) -> None:
|
|
atts = {'class': 'reference download',
|
|
'download': ''}
|
|
|
|
if not self.builder.download_support:
|
|
self.context.append('')
|
|
elif 'refuri' in node:
|
|
atts['class'] += ' external'
|
|
atts['href'] = node['refuri']
|
|
self.body.append(self.starttag(node, 'a', '', **atts))
|
|
self.context.append('</a>')
|
|
elif 'filename' in node:
|
|
atts['class'] += ' internal'
|
|
atts['href'] = posixpath.join(self.builder.dlpath,
|
|
urllib.parse.quote(node['filename']))
|
|
self.body.append(self.starttag(node, 'a', '', **atts))
|
|
self.context.append('</a>')
|
|
else:
|
|
self.context.append('')
|
|
|
|
def depart_download_reference(self, node: Element) -> None:
|
|
self.body.append(self.context.pop())
|
|
|
|
# overwritten
|
|
def visit_figure(self, node: Element) -> None:
|
|
# set align=default if align not specified to give a default style
|
|
node.setdefault('align', 'default')
|
|
|
|
return super().visit_figure(node)
|
|
|
|
# overwritten
|
|
def visit_image(self, node: Element) -> None:
|
|
olduri = node['uri']
|
|
# rewrite the URI if the environment knows about it
|
|
if olduri in self.builder.images:
|
|
node['uri'] = posixpath.join(self.builder.imgpath,
|
|
urllib.parse.quote(self.builder.images[olduri]))
|
|
|
|
if 'scale' in node:
|
|
# Try to figure out image height and width. Docutils does that too,
|
|
# but it tries the final file name, which does not necessarily exist
|
|
# yet at the time the HTML file is written.
|
|
if not ('width' in node and 'height' in node):
|
|
path = os.path.join(self.builder.srcdir, olduri) # type: ignore[has-type]
|
|
size = get_image_size(path)
|
|
if size is None:
|
|
logger.warning(
|
|
__('Could not obtain image size. :scale: option is ignored.'),
|
|
location=node,
|
|
)
|
|
else:
|
|
if 'width' not in node:
|
|
node['width'] = str(size[0])
|
|
if 'height' not in node:
|
|
node['height'] = str(size[1])
|
|
|
|
uri = node['uri']
|
|
if uri.lower().endswith(('svg', 'svgz')):
|
|
atts = {'src': uri}
|
|
if 'width' in node:
|
|
atts['width'] = node['width']
|
|
if 'height' in node:
|
|
atts['height'] = node['height']
|
|
if 'scale' in node:
|
|
if 'width' in atts:
|
|
atts['width'] = multiply_length(atts['width'], node['scale'])
|
|
if 'height' in atts:
|
|
atts['height'] = multiply_length(atts['height'], node['scale'])
|
|
atts['alt'] = node.get('alt', uri)
|
|
if 'align' in node:
|
|
atts['class'] = 'align-%s' % node['align']
|
|
self.body.append(self.emptytag(node, 'img', '', **atts))
|
|
return
|
|
|
|
super().visit_image(node)
|
|
|
|
# overwritten
|
|
def depart_image(self, node: Element) -> None:
|
|
if node['uri'].lower().endswith(('svg', 'svgz')):
|
|
pass
|
|
else:
|
|
super().depart_image(node)
|
|
|
|
def visit_toctree(self, node: Element) -> None:
|
|
# this only happens when formatting a toc from env.tocs -- in this
|
|
# case we don't want to include the subtree
|
|
raise nodes.SkipNode
|
|
|
|
def visit_index(self, node: Element) -> None:
|
|
raise nodes.SkipNode
|
|
|
|
def visit_tabular_col_spec(self, node: Element) -> None:
|
|
raise nodes.SkipNode
|
|
|
|
def visit_glossary(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_glossary(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_acks(self, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_acks(self, node: Element) -> None:
|
|
pass
|
|
|
|
def visit_hlist(self, node: Element) -> None:
|
|
self.body.append('<table class="hlist"><tr>')
|
|
|
|
def depart_hlist(self, node: Element) -> None:
|
|
self.body.append('</tr></table>\n')
|
|
|
|
def visit_hlistcol(self, node: Element) -> None:
|
|
self.body.append('<td>')
|
|
|
|
def depart_hlistcol(self, node: Element) -> None:
|
|
self.body.append('</td>')
|
|
|
|
# overwritten
|
|
def visit_Text(self, node: Text) -> None:
|
|
text = node.astext()
|
|
encoded = self.encode(text)
|
|
if self.protect_literal_text:
|
|
# moved here from base class's visit_literal to support
|
|
# more formatting in literal nodes
|
|
for token in self.words_and_spaces.findall(encoded):
|
|
if token.strip():
|
|
# protect literal text from line wrapping
|
|
self.body.append('<span class="pre">%s</span>' % token)
|
|
elif token in ' \n':
|
|
# allow breaks at whitespace
|
|
self.body.append(token)
|
|
else:
|
|
# protect runs of multiple spaces; the last one can wrap
|
|
self.body.append(' ' * (len(token) - 1) + ' ')
|
|
else:
|
|
if self.in_mailto and self.settings.cloak_email_addresses:
|
|
encoded = self.cloak_email(encoded)
|
|
self.body.append(encoded)
|
|
|
|
def visit_note(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'note')
|
|
|
|
def depart_note(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_warning(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'warning')
|
|
|
|
def depart_warning(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_attention(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'attention')
|
|
|
|
def depart_attention(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_caution(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'caution')
|
|
|
|
def depart_caution(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_danger(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'danger')
|
|
|
|
def depart_danger(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_error(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'error')
|
|
|
|
def depart_error(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_hint(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'hint')
|
|
|
|
def depart_hint(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_important(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'important')
|
|
|
|
def depart_important(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_tip(self, node: Element) -> None:
|
|
self.visit_admonition(node, 'tip')
|
|
|
|
def depart_tip(self, node: Element) -> None:
|
|
self.depart_admonition(node)
|
|
|
|
def visit_literal_emphasis(self, node: Element) -> None:
|
|
return self.visit_emphasis(node)
|
|
|
|
def depart_literal_emphasis(self, node: Element) -> None:
|
|
return self.depart_emphasis(node)
|
|
|
|
def visit_literal_strong(self, node: Element) -> None:
|
|
return self.visit_strong(node)
|
|
|
|
def depart_literal_strong(self, node: Element) -> None:
|
|
return self.depart_strong(node)
|
|
|
|
def visit_abbreviation(self, node: Element) -> None:
|
|
attrs = {}
|
|
if node.hasattr('explanation'):
|
|
attrs['title'] = node['explanation']
|
|
self.body.append(self.starttag(node, 'abbr', '', **attrs))
|
|
|
|
def depart_abbreviation(self, node: Element) -> None:
|
|
self.body.append('</abbr>')
|
|
|
|
def visit_manpage(self, node: Element) -> None:
|
|
self.visit_literal_emphasis(node)
|
|
if self.manpages_url:
|
|
node['refuri'] = self.manpages_url.format(**node.attributes)
|
|
self.visit_reference(node)
|
|
|
|
def depart_manpage(self, node: Element) -> None:
|
|
if self.manpages_url:
|
|
self.depart_reference(node)
|
|
self.depart_literal_emphasis(node)
|
|
|
|
# overwritten to add even/odd classes
|
|
|
|
def visit_table(self, node: Element) -> None:
|
|
self._table_row_indices.append(0)
|
|
|
|
atts = {}
|
|
classes = [cls.strip(' \t\n') for cls in self.settings.table_style.split(',')]
|
|
classes.insert(0, "docutils") # compat
|
|
|
|
# set align-default if align not specified to give a default style
|
|
classes.append('align-%s' % node.get('align', 'default'))
|
|
|
|
if 'width' in node:
|
|
atts['style'] = 'width: %s' % node['width']
|
|
tag = self.starttag(node, 'table', CLASS=' '.join(classes), **atts)
|
|
self.body.append(tag)
|
|
|
|
def depart_table(self, node: Element) -> None:
|
|
self._table_row_indices.pop()
|
|
super().depart_table(node)
|
|
|
|
def visit_row(self, node: Element) -> None:
|
|
self._table_row_indices[-1] += 1
|
|
if self._table_row_indices[-1] % 2 == 0:
|
|
node['classes'].append('row-even')
|
|
else:
|
|
node['classes'].append('row-odd')
|
|
self.body.append(self.starttag(node, 'tr', ''))
|
|
node.column = 0 # type: ignore[attr-defined]
|
|
|
|
def visit_field_list(self, node: Element) -> None:
|
|
self._fieldlist_row_indices.append(0)
|
|
return super().visit_field_list(node)
|
|
|
|
def depart_field_list(self, node: Element) -> None:
|
|
self._fieldlist_row_indices.pop()
|
|
return super().depart_field_list(node)
|
|
|
|
def visit_field(self, node: Element) -> None:
|
|
self._fieldlist_row_indices[-1] += 1
|
|
if self._fieldlist_row_indices[-1] % 2 == 0:
|
|
node['classes'].append('field-even')
|
|
else:
|
|
node['classes'].append('field-odd')
|
|
|
|
def visit_math(self, node: Element, math_env: str = '') -> None:
|
|
# see validate_math_renderer
|
|
name: str = self.builder.math_renderer_name # type: ignore[assignment]
|
|
visit, _ = self.builder.app.registry.html_inline_math_renderers[name]
|
|
visit(self, node)
|
|
|
|
def depart_math(self, node: Element, math_env: str = '') -> None:
|
|
# see validate_math_renderer
|
|
name: str = self.builder.math_renderer_name # type: ignore[assignment]
|
|
_, depart = self.builder.app.registry.html_inline_math_renderers[name]
|
|
if depart:
|
|
depart(self, node)
|
|
|
|
def visit_math_block(self, node: Element, math_env: str = '') -> None:
|
|
# see validate_math_renderer
|
|
name: str = self.builder.math_renderer_name # type: ignore[assignment]
|
|
visit, _ = self.builder.app.registry.html_block_math_renderers[name]
|
|
visit(self, node)
|
|
|
|
def depart_math_block(self, node: Element, math_env: str = '') -> None:
|
|
# see validate_math_renderer
|
|
name: str = self.builder.math_renderer_name # type: ignore[assignment]
|
|
_, depart = self.builder.app.registry.html_block_math_renderers[name]
|
|
if depart:
|
|
depart(self, node)
|
|
|
|
# See Docutils r9413
|
|
# Re-instate the footnote-reference class
|
|
def visit_footnote_reference(self, node):
|
|
href = '#' + node['refid']
|
|
classes = ['footnote-reference', self.settings.footnote_references]
|
|
self.body.append(self.starttag(node, 'a', suffix='', classes=classes,
|
|
role='doc-noteref', href=href))
|
|
self.body.append('<span class="fn-bracket">[</span>')
|