Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/writers/html5.py

@@ -40,7 +40,7 @@ def multiply_length(length: str, scale: int) -> str:
         return length
     amount, unit = matched.groups()
     result = float(amount) * scale / 100
-    return f"{int(result)}{unit}"
+    return f'{int(result)}{unit}'
 
 
 class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
@@ -168,7 +168,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         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]
+        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
@@ -205,7 +207,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     #
     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):
+        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
@@ -223,13 +227,18 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
             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)
+            len_lirp = len(self.list_is_required_param)
+            is_last_group = self.param_group_index + 1 == len_lirp
             next_is_required = (
                 not is_last_group
                 and self.list_is_required_param[self.param_group_index + 1]
-            )
+            )  # fmt: skip
             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):
+            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')
 
@@ -246,8 +255,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         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.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:
@@ -310,12 +320,16 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
             atts['class'] += ' external'
         if 'refuri' in node:
             atts['href'] = node['refuri'] or '#'
-            if self.settings.cloak_email_addresses and atts['href'].startswith('mailto:'):
+            if (
+                self.settings.cloak_email_addresses
+                and atts['href'].startswith('mailto:')
+            ):  # fmt: skip
                 atts['href'] = self.cloak_mailto(atts['href'])
                 self.in_mailto = True
         else:
-            assert 'refid' in node, \
-                   'References must have "refuri" or "refid" attribute.'
+            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
@@ -329,8 +343,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         self.body.append(self.starttag(node, 'a', '', **atts))
 
         if node.get('secnumber'):
-            self.body.append(('%s' + self.secnumber_suffix) %
-                             '.'.join(map(str, node['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)
@@ -344,8 +359,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
 
     # overwritten
     def visit_admonition(self, node: Element, name: str = '') -> None:
-        self.body.append(self.starttag(
-            node, 'div', CLASS=('admonition ' + name)))
+        self.body.append(self.starttag(node, 'div', CLASS=('admonition ' + name)))
         if name:
             node.insert(0, nodes.title(name, admonitionlabels[name]))
 
@@ -365,9 +379,10 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         if isinstance(node.parent, nodes.section):
             if self.builder.name == 'singlehtml':
                 docname = self.docnames[-1]
-                anchorname = "{}/#{}".format(docname, node.parent['ids'][0])
+                anchorname = f"{docname}/#{node.parent['ids'][0]}"
                 if anchorname not in self.builder.secnumbers:
-                    anchorname = "%s/" % docname  # try first heading which has no anchor
+                    # try first heading which has no anchor
+                    anchorname = f'{docname}/'
             else:
                 anchorname = '#' + node.parent['ids'][0]
                 if anchorname not in self.builder.secnumbers:
@@ -381,13 +396,15 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     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))
+            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}"
+                key = f'{self.docnames[-1]}/{figtype}'
             else:
                 key = figtype
 
@@ -402,7 +419,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
                     self.body.append(prefix % '.'.join(map(str, numbers)) + ' ')
                     self.body.append('</span>')
 
-        figtype = self.builder.env.domains['std'].get_enumerable_node_type(node)
+        figtype = self.builder.env.domains.standard_domain.get_enumerable_node_type(
+            node
+        )
         if figtype:
             if len(node['ids']) == 0:
                 msg = __('Any IDs not assigned for %s node') % node.tagname
@@ -466,8 +485,13 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
 
     # 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'))
+        if (
+            isinstance(node.parent, addnodes.compact_paragraph)
+            and node.parent.get('toctree')
+        ):  # fmt: skip
+            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:
@@ -478,11 +502,11 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
             self.body.append('<span class="caption-text">')
         # Partially revert https://sourceforge.net/p/docutils/code/9562/
         if (
-                isinstance(node.parent, nodes.topic)
-                and self.settings.toc_backlinks
-                and 'contents' in node.parent['classes']
-                and self.body[-1].startswith('<a ')
-                # TODO: only remove for EPUB
+            isinstance(node.parent, nodes.topic)
+            and self.settings.toc_backlinks
+            and 'contents' in node.parent['classes']
+            and self.body[-1].startswith('<a ')
+            # TODO: only remove for EPUB
         ):
             # remove <a class="reference internal" href="#top">
             self.body.pop()
@@ -490,17 +514,22 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
 
     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']):
+        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))
+                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'))
@@ -520,7 +549,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
                     __('unsupported rubric heading level: %s'),
                     level,
                     type='html',
-                    location=node
+                    location=node,
                 )
                 super().visit_rubric(node)
         else:
@@ -549,16 +578,24 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
             linenos = self.config.html_codeblock_linenos_style
 
         highlighted = self.highlighter.highlight_block(
-            node.rawsource, lang, opts=opts, linenos=linenos,
-            location=node, **highlight_args,
+            node.rawsource,
+            lang,
+            opts=opts,
+            linenos=linenos,
+            location=node,
+            **highlight_args,
+        )
+        starttag = self.starttag(
+            node, 'div', suffix='', CLASS='highlight-%s notranslate' % lang
         )
-        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'):
+        if (
+            isinstance(node.parent, nodes.container)
+            and node.parent.get('literal_block')
+        ):  # fmt: skip
             self.body.append('<div class="code-block-caption">')
         else:
             super().visit_caption(node)
@@ -569,14 +606,20 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         self.body.append('</span>')
 
         # append permalink if available
-        if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
+        if (
+            isinstance(node.parent, nodes.container)
+            and node.parent.get('literal_block')
+        ):  # fmt: skip
             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'):
+        if (
+            isinstance(node.parent, nodes.container)
+            and node.parent.get('literal_block')
+        ):  # fmt: skip
             self.body.append('</div>\n')
         else:
             super().depart_caption(node)
@@ -594,26 +637,29 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     # overwritten
     def visit_literal(self, node: Element) -> None:
         if 'kbd' in node['classes']:
-            self.body.append(self.starttag(node, 'kbd', '',
-                                           CLASS='docutils literal notranslate'))
+            self.body.append(
+                self.starttag(node, 'kbd', '', CLASS='docutils literal notranslate')
+            )
             return
-        lang = node.get("language", None)
+        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.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)
+            node.astext(), lang, opts=opts, location=node, nowrap=True
+        )
         starttag = self.starttag(
             node,
-            "code",
-            suffix="",
-            CLASS="docutils literal highlight highlight-%s" % lang,
+            'code',
+            suffix='',
+            CLASS='docutils literal highlight highlight-%s' % lang,
         )
-        self.body.append(starttag + highlighted.strip() + "</code>")
+        self.body.append(starttag + highlighted.strip() + '</code>')
         raise nodes.SkipNode
 
     def depart_literal(self, node: Element) -> None:
@@ -651,8 +697,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         pass
 
     def visit_centered(self, node: Element) -> None:
-        self.body.append(self.starttag(node, 'p', CLASS="centered") +
-                         '<strong>')
+        self.body.append(self.starttag(node, 'p', CLASS='centered') + '<strong>')
 
     def depart_centered(self, node: Element) -> None:
         self.body.append('</strong></p>')
@@ -664,8 +709,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         pass
 
     def visit_download_reference(self, node: Element) -> None:
-        atts = {'class': 'reference download',
-                'download': ''}
+        atts = {'class': 'reference download', 'download': ''}
 
         if not self.builder.download_support:
             self.context.append('')
@@ -676,8 +720,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
             self.context.append('</a>')
         elif 'filename' in node:
             atts['class'] += ' internal'
-            atts['href'] = posixpath.join(self.builder.dlpath,
-                                          urllib.parse.quote(node['filename']))
+            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:
@@ -698,8 +743,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
         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]))
+            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,
@@ -873,7 +919,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
 
         atts = {}
         classes = [cls.strip(' \t\n') for cls in self.settings.table_style.split(',')]
-        classes.insert(0, "docutils")  # compat
+        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'))
@@ -942,6 +988,9 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     def visit_footnote_reference(self, node: Element) -> None:
         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(
+            self.starttag(
+                node, 'a', suffix='', classes=classes, role='doc-noteref', href=href
+            )
+        )
         self.body.append('<span class="fn-bracket">[</span>')