IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Migrate to py3 style type annotation: sphinx.writers.html

Browse Source
This commit is contained in:
Takeshi KOMIYA 2019-10-14 18:37:23 +09:00
parent 5466906c7b
commit ab1369a837
1 changed files with 134 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

395
sphinx/writers/html.py
View File

@ -13,9 +13,11 @@ import os
import posixpath import posixpath
import sys import sys
import warnings import warnings
from typing import Iterable, cast from typing import cast
from typing import Iterable
from docutils import nodes from docutils import nodes
from docutils.nodes import Element, Node, Text
from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator
from sphinx import addnodes from sphinx import addnodes
@ -28,8 +30,7 @@ from sphinx.util.images import get_image_size
if False: if False:
# For type annotation # For type annotation
from typing import Any # NOQA from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.builders.html import StandaloneHTMLBuilder # NOQA
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@ -46,13 +47,11 @@ class HTMLWriter(Writer):
if '--embed-stylesheet' in _setting[1]: if '--embed-stylesheet' in _setting[1]:
_setting[2]['default'] = 0 _setting[2]['default'] = 0
def __init__(self, builder): def __init__(self, builder: "StandaloneHTMLBuilder") -> None:
# type: (StandaloneHTMLBuilder) -> None
super().__init__() super().__init__()
self.builder = builder self.builder = builder
def translate(self): def translate(self) -> None:
# type: () -> None
# sadly, this is mostly copied from parent class # sadly, this is mostly copied from parent class
visitor = self.builder.create_translator(self.document, self.builder) visitor = self.builder.create_translator(self.document, self.builder)
self.visitor = cast(HTMLTranslator, visitor) self.visitor = cast(HTMLTranslator, visitor)
@ -74,8 +73,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
builder = None # type: StandaloneHTMLBuilder builder = None # type: StandaloneHTMLBuilder
def __init__(self, *args): def __init__(self, *args) -> None:
# type: (Any) -> None
if isinstance(args[0], nodes.document) and isinstance(args[1], Builder): if isinstance(args[0], nodes.document) and isinstance(args[1], Builder):
document, builder = args document, builder = args
else: else:
@ -101,26 +99,21 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self._fieldlist_row_index = 0 self._fieldlist_row_index = 0
self.required_params_left = 0 self.required_params_left = 0
def visit_start_of_file(self, node): def visit_start_of_file(self, node: Element) -> None:
# type: (nodes.Element) -> None
# only occurs in the single-file builder # only occurs in the single-file builder
self.docnames.append(node['docname']) self.docnames.append(node['docname'])
self.body.append('<span id="document-%s"></span>' % node['docname']) self.body.append('<span id="document-%s"></span>' % node['docname'])
def depart_start_of_file(self, node): def depart_start_of_file(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.docnames.pop() self.docnames.pop()
def visit_desc(self, node): def visit_desc(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'dl', CLASS=node['objtype'])) self.body.append(self.starttag(node, 'dl', CLASS=node['objtype']))
def depart_desc(self, node): def depart_desc(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</dl>\n\n') self.body.append('</dl>\n\n')
def visit_desc_signature(self, node): def visit_desc_signature(self, node: Element) -> None:
# type: (nodes.Element) -> None
# the id is set automatically # the id is set automatically
self.body.append(self.starttag(node, 'dt')) self.body.append(self.starttag(node, 'dt'))
# anchor for per-desc interactive data # anchor for per-desc interactive data
@ -128,57 +121,45 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
and node['ids'] and node['first']: and node['ids'] and node['first']:
self.body.append('<!--[%s]-->' % node['ids'][0]) self.body.append('<!--[%s]-->' % node['ids'][0])
def depart_desc_signature(self, node): def depart_desc_signature(self, node: Element) -> None:
# type: (nodes.Element) -> None
if not node.get('is_multiline'): if not node.get('is_multiline'):
self.add_permalink_ref(node, _('Permalink to this definition')) self.add_permalink_ref(node, _('Permalink to this definition'))
self.body.append('</dt>\n') self.body.append('</dt>\n')
def visit_desc_signature_line(self, node): def visit_desc_signature_line(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_desc_signature_line(self, node): def depart_desc_signature_line(self, node: Element) -> None:
# type: (nodes.Element) -> None
if node.get('add_permalink'): if node.get('add_permalink'):
# the permalink info is on the parent desc_signature node # the permalink info is on the parent desc_signature node
self.add_permalink_ref(node.parent, _('Permalink to this definition')) self.add_permalink_ref(node.parent, _('Permalink to this definition'))
self.body.append('<br />') self.body.append('<br />')
def visit_desc_addname(self, node): def visit_desc_addname(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'code', '', CLASS='descclassname')) self.body.append(self.starttag(node, 'code', '', CLASS='descclassname'))
def depart_desc_addname(self, node): def depart_desc_addname(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</code>') self.body.append('</code>')
def visit_desc_type(self, node): def visit_desc_type(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_desc_type(self, node): def depart_desc_type(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_desc_returns(self, node): def visit_desc_returns(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(' &#x2192; ') self.body.append(' &#x2192; ')
def depart_desc_returns(self, node): def depart_desc_returns(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_desc_name(self, node): def visit_desc_name(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'code', '', CLASS='descname')) self.body.append(self.starttag(node, 'code', '', CLASS='descname'))
def depart_desc_name(self, node): def depart_desc_name(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</code>') self.body.append('</code>')
def visit_desc_parameterlist(self, node): def visit_desc_parameterlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('<span class="sig-paren">(</span>') self.body.append('<span class="sig-paren">(</span>')
self.first_param = 1 self.first_param = 1
self.optional_param_level = 0 self.optional_param_level = 0
@ -187,8 +168,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
for c in node.children]) for c in node.children])
self.param_separator = node.child_text_separator self.param_separator = node.child_text_separator
def depart_desc_parameterlist(self, node): def depart_desc_parameterlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('<span class="sig-paren">)</span>') self.body.append('<span class="sig-paren">)</span>')
# If required parameters are still to come, then put the comma after # If required parameters are still to come, then put the comma after
@ -197,8 +177,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
# #
# foo([a, ]b, c[, d]) # foo([a, ]b, c[, d])
# #
def visit_desc_parameter(self, node): def visit_desc_parameter(self, node: Element) -> None:
# type: (nodes.Element) -> None
if self.first_param: if self.first_param:
self.first_param = 0 self.first_param = 0
elif not self.required_params_left: elif not self.required_params_left:
@ -208,50 +187,40 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
if not node.hasattr('noemph'): if not node.hasattr('noemph'):
self.body.append('<em>') self.body.append('<em>')
def depart_desc_parameter(self, node): def depart_desc_parameter(self, node: Element) -> None:
# type: (nodes.Element) -> None
if not node.hasattr('noemph'): if not node.hasattr('noemph'):
self.body.append('</em>') self.body.append('</em>')
if self.required_params_left: if self.required_params_left:
self.body.append(self.param_separator) self.body.append(self.param_separator)
def visit_desc_optional(self, node): def visit_desc_optional(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.optional_param_level += 1 self.optional_param_level += 1
self.body.append('<span class="optional">[</span>') self.body.append('<span class="optional">[</span>')
def depart_desc_optional(self, node): def depart_desc_optional(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.optional_param_level -= 1 self.optional_param_level -= 1
self.body.append('<span class="optional">]</span>') self.body.append('<span class="optional">]</span>')
def visit_desc_annotation(self, node): def visit_desc_annotation(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'em', '', CLASS='property')) self.body.append(self.starttag(node, 'em', '', CLASS='property'))
def depart_desc_annotation(self, node): def depart_desc_annotation(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</em>') self.body.append('</em>')
def visit_desc_content(self, node): def visit_desc_content(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'dd', '')) self.body.append(self.starttag(node, 'dd', ''))
def depart_desc_content(self, node): def depart_desc_content(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</dd>') self.body.append('</dd>')
def visit_versionmodified(self, node): def visit_versionmodified(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'div', CLASS=node['type'])) self.body.append(self.starttag(node, 'div', CLASS=node['type']))
def depart_versionmodified(self, node): def depart_versionmodified(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</div>\n') self.body.append('</div>\n')
# overwritten # overwritten
def visit_reference(self, node): def visit_reference(self, node: Element) -> None:
# type: (nodes.Element) -> None
atts = {'class': 'reference'} atts = {'class': 'reference'}
if node.get('internal') or 'refuri' not in node: if node.get('internal') or 'refuri' not in node:
atts['class'] += ' internal' atts['class'] += ' internal'
@ -279,38 +248,31 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append(('%s' + self.secnumber_suffix) % self.body.append(('%s' + self.secnumber_suffix) %
'.'.join(map(str, node['secnumber']))) '.'.join(map(str, node['secnumber'])))
def visit_number_reference(self, node): def visit_number_reference(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_reference(node) self.visit_reference(node)
def depart_number_reference(self, node): def depart_number_reference(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_reference(node) self.depart_reference(node)
# overwritten -- we don't want source comments to show up in the HTML # overwritten -- we don't want source comments to show up in the HTML
def visit_comment(self, node): # type: ignore def visit_comment(self, node: Element) -> None: # type: ignore
# type: (nodes.Element) -> None
raise nodes.SkipNode raise nodes.SkipNode
# overwritten # overwritten
def visit_admonition(self, node, name=''): def visit_admonition(self, node: Element, name: str = '') -> None:
# type: (nodes.Element, str) -> None
self.body.append(self.starttag( self.body.append(self.starttag(
node, 'div', CLASS=('admonition ' + name))) node, 'div', CLASS=('admonition ' + name)))
if name: if name:
node.insert(0, nodes.title(name, admonitionlabels[name])) node.insert(0, nodes.title(name, admonitionlabels[name]))
self.set_first_last(node) self.set_first_last(node)
def visit_seealso(self, node): def visit_seealso(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'seealso') self.visit_admonition(node, 'seealso')
def depart_seealso(self, node): def depart_seealso(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def add_secnumber(self, node): def add_secnumber(self, node: Element) -> None:
# type: (nodes.Element) -> None
if node.get('secnumber'): if node.get('secnumber'):
self.body.append('.'.join(map(str, node['secnumber'])) + self.body.append('.'.join(map(str, node['secnumber'])) +
self.secnumber_suffix) self.secnumber_suffix)
@ -329,10 +291,8 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append('.'.join(map(str, numbers)) + self.body.append('.'.join(map(str, numbers)) +
self.secnumber_suffix) self.secnumber_suffix)
def add_fignumber(self, node): def add_fignumber(self, node: Element) -> None:
# type: (nodes.Element) -> None def append_fignumber(figtype: str, figure_id: str) -> None:
def append_fignumber(figtype, figure_id):
# type: (str, str) -> None
if self.builder.name == 'singlehtml': if self.builder.name == 'singlehtml':
key = "%s/%s" % (self.docnames[-1], figtype) key = "%s/%s" % (self.docnames[-1], figtype)
else: else:
@ -357,14 +317,12 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
else: else:
append_fignumber(figtype, node['ids'][0]) append_fignumber(figtype, node['ids'][0])
def add_permalink_ref(self, node, title): def add_permalink_ref(self, node: Element, title: str) -> None:
# type: (nodes.Element, str) -> None
if node['ids'] and self.permalink_text and self.builder.add_permalinks: if node['ids'] and self.permalink_text and self.builder.add_permalinks:
format = '<a class="headerlink" href="#%s" title="%s">%s</a>' format = '<a class="headerlink" href="#%s" title="%s">%s</a>'
self.body.append(format % (node['ids'][0], title, self.permalink_text)) self.body.append(format % (node['ids'][0], title, self.permalink_text))
def generate_targets_for_listing(self, node): def generate_targets_for_listing(self, node: Element) -> None:
# type: (nodes.Element) -> None
"""Generate hyperlink targets for listings. """Generate hyperlink targets for listings.
Original visit_bullet_list(), visit_definition_list() and visit_enumerated_list() Original visit_bullet_list(), visit_definition_list() and visit_enumerated_list()
@ -379,8 +337,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
node['ids'].remove(id) node['ids'].remove(id)
# overwritten # overwritten
def visit_bullet_list(self, node): def visit_bullet_list(self, node: Element) -> None:
# type: (nodes.Element) -> None
if len(node) == 1 and isinstance(node[0], addnodes.toctree): if len(node) == 1 and isinstance(node[0], addnodes.toctree):
# avoid emitting empty <ul></ul> # avoid emitting empty <ul></ul>
raise nodes.SkipNode raise nodes.SkipNode
@ -388,46 +345,39 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
super().visit_bullet_list(node) super().visit_bullet_list(node)
# overwritten # overwritten
def visit_enumerated_list(self, node): def visit_enumerated_list(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.generate_targets_for_listing(node) self.generate_targets_for_listing(node)
super().visit_enumerated_list(node) super().visit_enumerated_list(node)
# overwritten # overwritten
def visit_definition(self, node): def visit_definition(self, node: Element) -> None:
# type: (nodes.Element) -> None
# don't insert </dt> here. # don't insert </dt> here.
self.body.append(self.starttag(node, 'dd', '')) self.body.append(self.starttag(node, 'dd', ''))
# overwritten # overwritten
def depart_definition(self, node): def depart_definition(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</dd>\n') self.body.append('</dd>\n')
# overwritten # overwritten
def visit_classifier(self, node): def visit_classifier(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'span', '', CLASS='classifier')) self.body.append(self.starttag(node, 'span', '', CLASS='classifier'))
# overwritten # overwritten
def depart_classifier(self, node): def depart_classifier(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</span>') self.body.append('</span>')
next_node = node.next_node(descend=False, siblings=True) # type: nodes.Node next_node = node.next_node(descend=False, siblings=True) # type: Node
if not isinstance(next_node, nodes.classifier): if not isinstance(next_node, nodes.classifier):
# close `<dt>` tag at the tail of classifiers # close `<dt>` tag at the tail of classifiers
self.body.append('</dt>') self.body.append('</dt>')
# overwritten # overwritten
def visit_term(self, node): def visit_term(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'dt', '')) self.body.append(self.starttag(node, 'dt', ''))
# overwritten # overwritten
def depart_term(self, node): def depart_term(self, node: Element) -> None:
# type: (nodes.Element) -> None next_node = node.next_node(descend=False, siblings=True) # type: Node
next_node = node.next_node(descend=False, siblings=True) # type: nodes.Node
if isinstance(next_node, nodes.classifier): if isinstance(next_node, nodes.classifier):
# Leave the end tag to `self.depart_classifier()`, in case # Leave the end tag to `self.depart_classifier()`, in case
# there's a classifier. # there's a classifier.
@ -436,16 +386,14 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append('</dt>') self.body.append('</dt>')
# overwritten # overwritten
def visit_title(self, node): def visit_title(self, node: Element) -> None:
# type: (nodes.Element) -> None
super().visit_title(node) super().visit_title(node)
self.add_secnumber(node) self.add_secnumber(node)
self.add_fignumber(node.parent) self.add_fignumber(node.parent)
if isinstance(node.parent, nodes.table): if isinstance(node.parent, nodes.table):
self.body.append('<span class="caption-text">') self.body.append('<span class="caption-text">')
def depart_title(self, node): def depart_title(self, node: Element) -> None:
# type: (nodes.Element) -> None
close_tag = self.context[-1] close_tag = self.context[-1]
if (self.permalink_text and self.builder.add_permalinks and if (self.permalink_text and self.builder.add_permalinks and
node.parent.hasattr('ids') and node.parent['ids']): node.parent.hasattr('ids') and node.parent['ids']):
@ -467,8 +415,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
super().depart_title(node) super().depart_title(node)
# overwritten # overwritten
def visit_literal_block(self, node): def visit_literal_block(self, node: Element) -> None:
# type: (nodes.Element) -> None
if node.rawsource != node.astext(): if node.rawsource != node.astext():
# most probably a parsed-literal block -- don't highlight # most probably a parsed-literal block -- don't highlight
return super().visit_literal_block(node) return super().visit_literal_block(node)
@ -492,8 +439,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append(starttag + highlighted + '</div>\n') self.body.append(starttag + highlighted + '</div>\n')
raise nodes.SkipNode raise nodes.SkipNode
def visit_caption(self, node): def visit_caption(self, node: Element) -> None:
# type: (nodes.Element) -> None
if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'): if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
self.body.append('<div class="code-block-caption">') self.body.append('<div class="code-block-caption">')
else: else:
@ -501,8 +447,7 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.add_fignumber(node.parent) self.add_fignumber(node.parent)
self.body.append(self.starttag(node, 'span', '', CLASS='caption-text')) self.body.append(self.starttag(node, 'span', '', CLASS='caption-text'))
def depart_caption(self, node): def depart_caption(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</span>') self.body.append('</span>')
# append permalink if available # append permalink if available
@ -518,22 +463,18 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
else: else:
super().depart_caption(node) super().depart_caption(node)
def visit_doctest_block(self, node): def visit_doctest_block(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_literal_block(node) self.visit_literal_block(node)
# overwritten to add the <div> (for XHTML compliance) # overwritten to add the <div> (for XHTML compliance)
def visit_block_quote(self, node): def visit_block_quote(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'blockquote') + '<div>') self.body.append(self.starttag(node, 'blockquote') + '<div>')
def depart_block_quote(self, node): def depart_block_quote(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</div></blockquote>\n') self.body.append('</div></blockquote>\n')
# overwritten # overwritten
def visit_literal(self, node): def visit_literal(self, node: Element) -> None:
# type: (nodes.Element) -> None
if 'kbd' in node['classes']: if 'kbd' in node['classes']:
self.body.append(self.starttag(node, 'kbd', '', self.body.append(self.starttag(node, 'kbd', '',
CLASS='docutils literal notranslate')) CLASS='docutils literal notranslate'))
@ -542,16 +483,14 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
CLASS='docutils literal notranslate')) CLASS='docutils literal notranslate'))
self.protect_literal_text += 1 self.protect_literal_text += 1
def depart_literal(self, node): def depart_literal(self, node: Element) -> None:
# type: (nodes.Element) -> None
if 'kbd' in node['classes']: if 'kbd' in node['classes']:
self.body.append('</kbd>') self.body.append('</kbd>')
else: else:
self.protect_literal_text -= 1 self.protect_literal_text -= 1
self.body.append('</code>') self.body.append('</code>')
def visit_productionlist(self, node): def visit_productionlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'pre')) self.body.append(self.starttag(node, 'pre'))
names = [] names = []
productionlist = cast(Iterable[addnodes.production], node) productionlist = cast(Iterable[addnodes.production], node)
@ -571,30 +510,24 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append('</pre>\n') self.body.append('</pre>\n')
raise nodes.SkipNode raise nodes.SkipNode
def depart_productionlist(self, node): def depart_productionlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_production(self, node): def visit_production(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_production(self, node): def depart_production(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_centered(self, node): def visit_centered(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.starttag(node, 'p', CLASS="centered") + self.body.append(self.starttag(node, 'p', CLASS="centered") +
'<strong>') '<strong>')
def depart_centered(self, node): def depart_centered(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</strong></p>') self.body.append('</strong></p>')
# overwritten # overwritten
def should_be_compact_paragraph(self, node): def should_be_compact_paragraph(self, node: Node) -> bool:
# type: (nodes.Node) -> bool
"""Determine if the <p> tags around paragraph can be omitted.""" """Determine if the <p> tags around paragraph can be omitted."""
if isinstance(node.parent, addnodes.desc_content): if isinstance(node.parent, addnodes.desc_content):
# Never compact desc_content items. # Never compact desc_content items.
@ -604,16 +537,13 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
return False return False
return super().should_be_compact_paragraph(node) return super().should_be_compact_paragraph(node)
def visit_compact_paragraph(self, node): def visit_compact_paragraph(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_compact_paragraph(self, node): def depart_compact_paragraph(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_download_reference(self, node): def visit_download_reference(self, node: Element) -> None:
# type: (nodes.Element) -> None
atts = {'class': 'reference download', atts = {'class': 'reference download',
'download': ''} 'download': ''}
@ -632,13 +562,11 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
else: else:
self.context.append('') self.context.append('')
def depart_download_reference(self, node): def depart_download_reference(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append(self.context.pop()) self.body.append(self.context.pop())
# overwritten # overwritten
def visit_image(self, node): def visit_image(self, node: Element) -> None:
# type: (nodes.Element) -> None
olduri = node['uri'] olduri = node['uri']
# rewrite the URI if the environment knows about it # rewrite the URI if the environment knows about it
if olduri in self.builder.images: if olduri in self.builder.images:
@ -679,67 +607,53 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
super().visit_image(node) super().visit_image(node)
# overwritten # overwritten
def depart_image(self, node): def depart_image(self, node: Element) -> None:
# type: (nodes.Element) -> None
if node['uri'].lower().endswith(('svg', 'svgz')): if node['uri'].lower().endswith(('svg', 'svgz')):
self.body.append(self.context.pop()) self.body.append(self.context.pop())
else: else:
super().depart_image(node) super().depart_image(node)
def visit_toctree(self, node): def visit_toctree(self, node: Element) -> None:
# type: (nodes.Element) -> None
# this only happens when formatting a toc from env.tocs -- in this # this only happens when formatting a toc from env.tocs -- in this
# case we don't want to include the subtree # case we don't want to include the subtree
raise nodes.SkipNode raise nodes.SkipNode
def visit_index(self, node): def visit_index(self, node: Element) -> None:
# type: (nodes.Element) -> None
raise nodes.SkipNode raise nodes.SkipNode
def visit_tabular_col_spec(self, node): def visit_tabular_col_spec(self, node: Element) -> None:
# type: (nodes.Element) -> None
raise nodes.SkipNode raise nodes.SkipNode
def visit_glossary(self, node): def visit_glossary(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_glossary(self, node): def depart_glossary(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_acks(self, node): def visit_acks(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def depart_acks(self, node): def depart_acks(self, node: Element) -> None:
# type: (nodes.Element) -> None
pass pass
def visit_hlist(self, node): def visit_hlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('<table class="hlist"><tr>') self.body.append('<table class="hlist"><tr>')
def depart_hlist(self, node): def depart_hlist(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</tr></table>\n') self.body.append('</tr></table>\n')
def visit_hlistcol(self, node): def visit_hlistcol(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('<td>') self.body.append('<td>')
def depart_hlistcol(self, node): def depart_hlistcol(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</td>') self.body.append('</td>')
def visit_option_group(self, node): def visit_option_group(self, node: Element) -> None:
# type: (nodes.Element) -> None
super().visit_option_group(node) super().visit_option_group(node)
self.context[-2] = self.context[-2].replace('&nbsp;', '&#160;') self.context[-2] = self.context[-2].replace('&nbsp;', '&#160;')
# overwritten # overwritten
def visit_Text(self, node): def visit_Text(self, node: Text) -> None:
# type: (nodes.Text) -> None
text = node.astext() text = node.astext()
encoded = self.encode(text) encoded = self.encode(text)
if self.protect_literal_text: if self.protect_literal_text:
@ -760,127 +674,99 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
encoded = self.cloak_email(encoded) encoded = self.cloak_email(encoded)
self.body.append(encoded) self.body.append(encoded)
def visit_note(self, node): def visit_note(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'note') self.visit_admonition(node, 'note')
def depart_note(self, node): def depart_note(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_warning(self, node): def visit_warning(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'warning') self.visit_admonition(node, 'warning')
def depart_warning(self, node): def depart_warning(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_attention(self, node): def visit_attention(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'attention') self.visit_admonition(node, 'attention')
def depart_attention(self, node): def depart_attention(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_caution(self, node): def visit_caution(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'caution') self.visit_admonition(node, 'caution')
def depart_caution(self, node): def depart_caution(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_danger(self, node): def visit_danger(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'danger') self.visit_admonition(node, 'danger')
def depart_danger(self, node): def depart_danger(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_error(self, node): def visit_error(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'error') self.visit_admonition(node, 'error')
def depart_error(self, node): def depart_error(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_hint(self, node): def visit_hint(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'hint') self.visit_admonition(node, 'hint')
def depart_hint(self, node): def depart_hint(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_important(self, node): def visit_important(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'important') self.visit_admonition(node, 'important')
def depart_important(self, node): def depart_important(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_tip(self, node): def visit_tip(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_admonition(node, 'tip') self.visit_admonition(node, 'tip')
def depart_tip(self, node): def depart_tip(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.depart_admonition(node) self.depart_admonition(node)
def visit_literal_emphasis(self, node): def visit_literal_emphasis(self, node: Element) -> None:
# type: (nodes.Element) -> None
return self.visit_emphasis(node) return self.visit_emphasis(node)
def depart_literal_emphasis(self, node): def depart_literal_emphasis(self, node: Element) -> None:
# type: (nodes.Element) -> None
return self.depart_emphasis(node) return self.depart_emphasis(node)
def visit_literal_strong(self, node): def visit_literal_strong(self, node: Element) -> None:
# type: (nodes.Element) -> None
return self.visit_strong(node) return self.visit_strong(node)
def depart_literal_strong(self, node): def depart_literal_strong(self, node: Element) -> None:
# type: (nodes.Element) -> None
return self.depart_strong(node) return self.depart_strong(node)
def visit_abbreviation(self, node): def visit_abbreviation(self, node: Element) -> None:
# type: (nodes.Element) -> None
attrs = {} attrs = {}
if node.hasattr('explanation'): if node.hasattr('explanation'):
attrs['title'] = node['explanation'] attrs['title'] = node['explanation']
self.body.append(self.starttag(node, 'abbr', '', **attrs)) self.body.append(self.starttag(node, 'abbr', '', **attrs))
def depart_abbreviation(self, node): def depart_abbreviation(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.body.append('</abbr>') self.body.append('</abbr>')
def visit_manpage(self, node): def visit_manpage(self, node: Element) -> None:
# type: (nodes.Element) -> None
self.visit_literal_emphasis(node) self.visit_literal_emphasis(node)
if self.manpages_url: if self.manpages_url:
node['refuri'] = self.manpages_url.format(**node.attributes) node['refuri'] = self.manpages_url.format(**node.attributes)
self.visit_reference(node) self.visit_reference(node)
def depart_manpage(self, node): def depart_manpage(self, node: Element) -> None:
# type: (nodes.Element) -> None
if self.manpages_url: if self.manpages_url:
self.depart_reference(node) self.depart_reference(node)
self.depart_literal_emphasis(node) self.depart_literal_emphasis(node)
# overwritten to add even/odd classes # overwritten to add even/odd classes
def visit_table(self, node): def visit_table(self, node: Element) -> None:
# type: (nodes.Element) -> None
self._table_row_index = 0 self._table_row_index = 0
return super().visit_table(node) return super().visit_table(node)
def visit_row(self, node): def visit_row(self, node: Element) -> None:
# type: (nodes.Element) -> None
self._table_row_index += 1 self._table_row_index += 1
if self._table_row_index % 2 == 0: if self._table_row_index % 2 == 0:
node['classes'].append('row-even') node['classes'].append('row-even')
@ -889,19 +775,16 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
self.body.append(self.starttag(node, 'tr', '')) self.body.append(self.starttag(node, 'tr', ''))
node.column = 0 # type: ignore node.column = 0 # type: ignore
def visit_entry(self, node): def visit_entry(self, node: Element) -> None:
# type: (nodes.Element) -> None
super().visit_entry(node) super().visit_entry(node)
if self.body[-1] == '&nbsp;': if self.body[-1] == '&nbsp;':
self.body[-1] = '&#160;' self.body[-1] = '&#160;'
def visit_field_list(self, node): def visit_field_list(self, node: Element) -> None:
# type: (nodes.Element) -> None
self._fieldlist_row_index = 0 self._fieldlist_row_index = 0
return super().visit_field_list(node) return super().visit_field_list(node)
def visit_field(self, node): def visit_field(self, node: Element) -> None:
# type: (nodes.Element) -> None
self._fieldlist_row_index += 1 self._fieldlist_row_index += 1
if self._fieldlist_row_index % 2 == 0: if self._fieldlist_row_index % 2 == 0:
node['classes'].append('field-even') node['classes'].append('field-even')
@ -909,69 +792,59 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
node['classes'].append('field-odd') node['classes'].append('field-odd')
self.body.append(self.starttag(node, 'tr', '', CLASS='field')) self.body.append(self.starttag(node, 'tr', '', CLASS='field'))
def visit_field_name(self, node): def visit_field_name(self, node: Element) -> None:
# type: (nodes.Element) -> None
context_count = len(self.context) context_count = len(self.context)
super().visit_field_name(node) super().visit_field_name(node)
if context_count != len(self.context): if context_count != len(self.context):
self.context[-1] = self.context[-1].replace('&nbsp;', '&#160;') self.context[-1] = self.context[-1].replace('&nbsp;', '&#160;')
def visit_math(self, node, math_env=''): def visit_math(self, node: Element, math_env: str = '') -> None:
# type: (nodes.Element, str) -> None
name = self.builder.math_renderer_name name = self.builder.math_renderer_name
visit, _ = self.builder.app.registry.html_inline_math_renderers[name] visit, _ = self.builder.app.registry.html_inline_math_renderers[name]
visit(self, node) visit(self, node)
def depart_math(self, node, math_env=''): def depart_math(self, node: Element, math_env: str = '') -> None:
# type: (nodes.Element, str) -> None
name = self.builder.math_renderer_name name = self.builder.math_renderer_name
_, depart = self.builder.app.registry.html_inline_math_renderers[name] _, depart = self.builder.app.registry.html_inline_math_renderers[name]
if depart: if depart:
depart(self, node) depart(self, node)
def visit_math_block(self, node, math_env=''): def visit_math_block(self, node: Element, math_env: str = '') -> None:
# type: (nodes.Element, str) -> None
name = self.builder.math_renderer_name name = self.builder.math_renderer_name
visit, _ = self.builder.app.registry.html_block_math_renderers[name] visit, _ = self.builder.app.registry.html_block_math_renderers[name]
visit(self, node) visit(self, node)
def depart_math_block(self, node, math_env=''): def depart_math_block(self, node: Element, math_env: str = '') -> None:
# type: (nodes.Element, str) -> None
name = self.builder.math_renderer_name name = self.builder.math_renderer_name
_, depart = self.builder.app.registry.html_block_math_renderers[name] _, depart = self.builder.app.registry.html_block_math_renderers[name]
if depart: if depart:
depart(self, node) depart(self, node)
def unknown_visit(self, node): def unknown_visit(self, node: Node) -> None:
# type: (nodes.Node) -> None
raise NotImplementedError('Unknown node: ' + node.__class__.__name__) raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
# --------- METHODS FOR COMPATIBILITY -------------------------------------- # --------- METHODS FOR COMPATIBILITY --------------------------------------
@property @property
def highlightlang(self): def highlightlang(self) -> str:
# type: () -> str
warnings.warn('HTMLTranslator.highlightlang is deprecated.', warnings.warn('HTMLTranslator.highlightlang is deprecated.',
RemovedInSphinx30Warning, stacklevel=2) RemovedInSphinx30Warning, stacklevel=2)
return self.builder.config.highlight_language return self.builder.config.highlight_language
@property @property
def highlightlang_base(self): def highlightlang_base(self) -> str:
# type: () -> str
warnings.warn('HTMLTranslator.highlightlang_base is deprecated.', warnings.warn('HTMLTranslator.highlightlang_base is deprecated.',
RemovedInSphinx30Warning) RemovedInSphinx30Warning)
return self.builder.config.highlight_language return self.builder.config.highlight_language
@property @property
def highlightopts(self): def highlightopts(self) -> str:
# type: () -> str
warnings.warn('HTMLTranslator.highlightopts is deprecated.', warnings.warn('HTMLTranslator.highlightopts is deprecated.',
RemovedInSphinx30Warning, stacklevel=2) RemovedInSphinx30Warning, stacklevel=2)
return self.builder.config.highlight_options return self.builder.config.highlight_options
@property @property
def highlightlinenothreshold(self): def highlightlinenothreshold(self) -> int:
# type: () -> int
warnings.warn('HTMLTranslator.highlightlinenothreshold is deprecated.', warnings.warn('HTMLTranslator.highlightlinenothreshold is deprecated.',
RemovedInSphinx30Warning, stacklevel=2) RemovedInSphinx30Warning, stacklevel=2)
return sys.maxsize return sys.maxsize