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

sphinx/writers/manpage.py

@@ -98,8 +98,10 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
         if self.config.today:
             self._docinfo['date'] = self.config.today
         else:
-            self._docinfo['date'] = format_date(self.config.today_fmt or _('%b %d, %Y'),
-                                                language=self.config.language)
+            today_fmt = self.config.today_fmt or _('%b %d, %Y')
+            self._docinfo['date'] = format_date(
+                today_fmt, language=self.config.language
+            )
         self._docinfo['copyright'] = self.config.copyright
         self._docinfo['version'] = self.config.version
         self._docinfo['manual_group'] = self.config.project
@@ -110,11 +112,12 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
 
     # overwritten -- added quotes around all .TH arguments
     def header(self) -> str:
-        tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\""
-                " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n")
+        tmpl = (
+            '.TH "%(title_upper)s" "%(manual_section)s"'
+            ' "%(date)s" "%(version)s" "%(manual_group)s"\n'
+        )
         if self._docinfo['subtitle']:
-            tmpl += (".SH NAME\n"
-                     "%(title)s \\- %(subtitle)s\n")
+            tmpl += '.SH NAME\n' '%(title)s \\- %(subtitle)s\n'
         return tmpl % self._docinfo
 
     def visit_start_of_file(self, node: Element) -> None:
@@ -312,7 +315,7 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
         is_safe_to_click = uri.startswith(('mailto:', 'http:', 'https:', 'ftp:'))
         if is_safe_to_click:
             # OSC 8 link start (using groff's device control directive).
-            self.body.append(fr"\X'tty: link {uri}'")
+            self.body.append(rf"\X'tty: link {uri}'")
 
         self.body.append(self.defs['reference'][0])
         # avoid repeating escaping code... fine since
@@ -323,12 +326,14 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
         if uri and not uri.startswith('#'):
             # if configured, put the URL after the link
             if self.config.man_show_urls and node.astext() != uri:
-                if uri.startswith('mailto:'):
-                    uri = uri[7:]
+                uri = uri.removeprefix('mailto:')
                 self.body.extend([
                     ' <',
-                    self.defs['strong'][0], uri, self.defs['strong'][1],
-                    '>'])
+                    self.defs['strong'][0],
+                    uri,
+                    self.defs['strong'][1],
+                    '>',
+                ])
         if is_safe_to_click:
             # OSC 8 link end.
             self.body.append(r"\X'tty: link'")
@@ -421,13 +426,19 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
 
     # overwritten: handle section titles better than in 0.6 release
     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('.sp\n')
         else:
             super().visit_caption(node)
 
     def depart_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('\n')
         else:
             super().depart_caption(node)
@@ -442,8 +453,7 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[mi
                 # skip the document title
                 raise nodes.SkipNode
             elif self.section_level == 1:
-                self.body.append('.SH %s\n' %
-                                 self.deunicode(node.astext().upper()))
+                self.body.append(f'.SH {self.deunicode(node.astext().upper())}\n')
                 raise nodes.SkipNode
         return super().visit_title(node)
 

sphinx/writers/texinfo.py

@@ -6,12 +6,11 @@ import re
 import textwrap
 from collections.abc import Iterable, Iterator
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
 
 from sphinx import __display_version__, addnodes
-from sphinx.domains.index import IndexDomain
 from sphinx.errors import ExtensionError
 from sphinx.locale import _, __, admonitionlabels
 from sphinx.util import logging
@@ -39,13 +38,13 @@ Copyright @copyright{} %(copyright)s
 @end quotation
 """
 
-TEMPLATE = """\
+TEMPLATE = f"""\
 \\input texinfo   @c -*-texinfo-*-
 @c %%**start of header
 @setfilename %(filename)s
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx """ + __display_version__ + """.@*
+@*Generated by Sphinx {__display_version__}.@*
 @end ifinfo
 @settitle %(title)s
 @defindex ge
@@ -105,20 +104,23 @@ def smart_capwords(s: str, sep: str | None = None) -> str:
     return (sep or ' ').join(words)
 
 
-class TexinfoWriter(writers.Writer):  # type: ignore[misc]
+class TexinfoWriter(writers.Writer):  # type: ignore[type-arg]
     """Texinfo writer for generating Texinfo documents."""
 
     supported = ('texinfo', 'texi')
 
-    settings_spec: tuple[str, Any, tuple[tuple[str, list[str], dict[str, str]], ...]] = (
-        'Texinfo Specific Options', None, (
-            ("Name of the Info file", ['--texinfo-filename'], {'default': ''}),
+    settings_spec = (
+        'Texinfo Specific Options',
+        None,
+        (
+            ('Name of the Info file', ['--texinfo-filename'], {'default': ''}),
             ('Dir entry', ['--texinfo-dir-entry'], {'default': ''}),
             ('Description', ['--texinfo-dir-description'], {'default': ''}),
-            ('Category', ['--texinfo-dir-category'], {'default':
-                                                      'Miscellaneous'})))
+            ('Category', ['--texinfo-dir-category'], {'default': 'Miscellaneous'}),
+        ),
+    )
 
-    settings_defaults: dict[str, Any] = {}
+    settings_defaults: ClassVar[dict[str, Any]] = {}
 
     output: str
 
@@ -129,6 +131,7 @@ class TexinfoWriter(writers.Writer):  # type: ignore[misc]
         self.builder = builder
 
     def translate(self) -> None:
+        assert isinstance(self.document, nodes.document)
         visitor = self.builder.create_translator(self.document, self.builder)
         self.visitor = cast(TexinfoTranslator, visitor)
         self.document.walkabout(visitor)
@@ -138,7 +141,6 @@ class TexinfoWriter(writers.Writer):  # type: ignore[misc]
 
 
 class TexinfoTranslator(SphinxTranslator):
-
     ignore_missing_images = False
     builder: TexinfoBuilder
 
@@ -161,14 +163,14 @@ class TexinfoTranslator(SphinxTranslator):
         super().__init__(document, builder)
         self.init_settings()
 
-        self.written_ids: set[str] = set()          # node names and anchors in output
+        self.written_ids: set[str] = set()  # node names and anchors in output
         # node names and anchors that should be in output
         self.referenced_ids: set[str] = set()
-        self.indices: list[tuple[str, str]] = []    # (node name, content)
-        self.short_ids: dict[str, str] = {}         # anchors --> short ids
-        self.node_names: dict[str, str] = {}        # node name --> node's name to display
+        self.indices: list[tuple[str, str]] = []  # (node name, content)
+        self.short_ids: dict[str, str] = {}  # anchors --> short ids
+        self.node_names: dict[str, str] = {}  # node name --> node's name to display
         self.node_menus: dict[str, list[str]] = {}  # node name --> node's menu entries
-        self.rellinks: dict[str, list[str]] = {}    # node name --> (next, previous, up)
+        self.rellinks: dict[str, list[str]] = {}  # node name --> (next, previous, up)
 
         self.collect_indices()
         self.collect_node_names()
@@ -213,6 +215,10 @@ class TexinfoTranslator(SphinxTranslator):
     # -- Helper routines
 
     def init_settings(self) -> None:
+        today_fmt = self.config.today_fmt or _('%b %d, %Y')
+        today = self.config.today or format_date(
+            today_fmt, language=self.config.language
+        )
         elements = self.elements = self.default_elements.copy()
         elements.update({
             # if empty, the title is set to the first section title
@@ -223,9 +229,7 @@ class TexinfoTranslator(SphinxTranslator):
             'release': self.escape(self.config.release),
             'project': self.escape(self.config.project),
             'copyright': self.escape(self.config.copyright),
-            'date': self.escape(self.config.today or
-                                format_date(self.config.today_fmt or _('%b %d, %Y'),
-                                            language=self.config.language)),
+            'date': self.escape(today),
         })
         # title
         title: str = self.settings.title
@@ -244,12 +248,11 @@ class TexinfoTranslator(SphinxTranslator):
             entry = self.format_menu_entry(
                 self.escape_menu(self.settings.texinfo_dir_entry),
                 '(%s)' % elements['filename'],
-                self.escape_arg(self.settings.texinfo_dir_description))
-            elements['direntry'] = ('@dircategory %s\n'
-                                    '@direntry\n'
-                                    '%s'
-                                    '@end direntry\n') % (
-                self.escape_id(self.settings.texinfo_dir_category), entry)
+                self.escape_arg(self.settings.texinfo_dir_description),
+            )
+            elements['direntry'] = (
+                '@dircategory %s\n' '@direntry\n' '%s' '@end direntry\n'
+            ) % (self.escape_id(self.settings.texinfo_dir_category), entry)
         elements['copying'] = COPYING % elements
         # allow the user to override them all
         elements.update(self.settings.texinfo_elements)
@@ -263,8 +266,10 @@ class TexinfoTranslator(SphinxTranslator):
         def add_node_name(name: str) -> str:
             node_id = self.escape_id(name)
             nth, suffix = 1, ''
-            while node_id + suffix in self.written_ids or \
-                    node_id + suffix in self.node_names:
+            while (
+                node_id + suffix in self.written_ids
+                or node_id + suffix in self.node_names
+            ):
                 nth += 1
                 suffix = '<%s>' % nth
             node_id += suffix
@@ -277,8 +282,9 @@ class TexinfoTranslator(SphinxTranslator):
         add_node_name('Top')
         add_node_name('top')
         # each index is a node
-        self.indices = [(add_node_name(name), content)
-                        for name, content in self.indices]
+        self.indices = [
+            (add_node_name(name), content) for name, content in self.indices
+        ]
         # each section is also a node
         for section in self.document.findall(nodes.section):
             title = cast(nodes.TextElement, section.next_node(nodes.Titular))  # type: ignore[type-var]
@@ -349,7 +355,7 @@ class TexinfoTranslator(SphinxTranslator):
         s = s.replace('{', '@{')
         s = s.replace('}', '@}')
         # prevent `` and '' quote conversion
-        s = s.replace('``', "`@w{`}")
+        s = s.replace('``', '`@w{`}')
         s = s.replace("''", "'@w{'}")
         return s
 
@@ -393,8 +399,9 @@ class TexinfoTranslator(SphinxTranslator):
         else:
             s = f'* {name}: {node_name}. '
         offset = max((24, (len(name) + 4) % 78))
-        wdesc = '\n'.join(' ' * offset + l for l in
-                          textwrap.wrap(desc, width=78 - offset))
+        wdesc = '\n'.join(
+            ' ' * offset + l for l in textwrap.wrap(desc, width=78 - offset)
+        )
         return s + wdesc.strip() + '\n'
 
     def add_menu_entries(
@@ -424,9 +431,11 @@ class TexinfoTranslator(SphinxTranslator):
             return
         self.body.append('\n@menu\n')
         self.add_menu_entries(entries)
-        if (node_name != 'Top' or
-                not self.node_menus[entries[0]] or
-                self.config.texinfo_no_detailmenu):
+        if (
+            node_name != 'Top'
+            or not self.node_menus[entries[0]]
+            or self.config.texinfo_no_detailmenu
+        ):
             self.body.append('\n@end menu\n')
             return
 
@@ -439,12 +448,10 @@ class TexinfoTranslator(SphinxTranslator):
             for subentry in entries:
                 _add_detailed_menu(subentry)
 
-        self.body.append('\n@detailmenu\n'
-                         ' --- The Detailed Node Listing ---\n')
+        self.body.append('\n@detailmenu\n' ' --- The Detailed Node Listing ---\n')
         for entry in entries:
             _add_detailed_menu(entry)
-        self.body.append('\n@end detailmenu\n'
-                         '@end menu\n')
+        self.body.append('\n@end detailmenu\n' '@end menu\n')
 
     def tex_image_length(self, width_str: str) -> str:
         match = re.match(r'(\d*\.?\d*)\s*(\S*)', width_str)
@@ -453,16 +460,18 @@ class TexinfoTranslator(SphinxTranslator):
             return width_str
         res = width_str
         amount, unit = match.groups()[:2]
-        if not unit or unit == "px":
+        if not unit or unit == 'px':
             # pixels: let TeX alone
             return ''
-        elif unit == "%":
+        elif unit == '%':
             # a4paper: textwidth=418.25368pt
-            res = "%d.0pt" % (float(amount) * 4.1825368)
+            res = '%d.0pt' % (float(amount) * 4.1825368)
         return res
 
     def collect_indices(self) -> None:
-        def generate(content: list[tuple[str, list[IndexEntry]]], collapsed: bool) -> str:
+        def generate(
+            content: list[tuple[str, list[IndexEntry]]], collapsed: bool
+        ) -> str:
             ret = ['\n@menu\n']
             for _letter, entries in content:
                 for entry in entries:
@@ -482,21 +491,21 @@ class TexinfoTranslator(SphinxTranslator):
                 indices_config = frozenset(indices_config)
             else:
                 check_names = False
-            for domain_name in sorted(self.builder.env.domains):
-                domain = self.builder.env.domains[domain_name]
+            for domain in self.builder.env.domains.sorted():
                 for index_cls in domain.indices:
                     index_name = f'{domain.name}-{index_cls.name}'
                     if check_names and index_name not in indices_config:
                         continue
                     content, collapsed = index_cls(domain).generate(
-                        self.builder.docnames)
+                        self.builder.docnames
+                    )
                     if content:
                         self.indices.append((
                             index_cls.localname,
                             generate(content, collapsed),
                         ))
         # only add the main Index if it's not empty
-        domain = cast(IndexDomain, self.builder.env.get_domain('index'))
+        domain = self.builder.env.domains.index_domain
         for docname in self.builder.docnames:
             if domain.entries[docname]:
                 self.indices.append((_('Index'), '\n@printindex ge\n'))
@@ -506,7 +515,7 @@ class TexinfoTranslator(SphinxTranslator):
     # TODO: move this to sphinx.util
 
     def collect_footnotes(
-        self, node: Element,
+        self, node: Element
     ) -> dict[str, list[collected_footnote | bool]]:
         def footnotes_under(n: Element) -> Iterator[nodes.footnote]:
             if isinstance(n, nodes.footnote):
@@ -517,6 +526,7 @@ class TexinfoTranslator(SphinxTranslator):
                         continue
                     elif isinstance(c, nodes.Element):
                         yield from footnotes_under(c)
+
         fnotes: dict[str, list[collected_footnote | bool]] = {}
         for fn in footnotes_under(node):
             label = cast(nodes.label, fn[0])
@@ -628,9 +638,13 @@ class TexinfoTranslator(SphinxTranslator):
         if isinstance(parent, nodes.Admonition | nodes.sidebar | nodes.topic):
             raise nodes.SkipNode
         if not isinstance(parent, nodes.section):
-            logger.warning(__('encountered title node not in section, topic, table, '
-                              'admonition or sidebar'),
-                           location=node)
+            logger.warning(
+                __(
+                    'encountered title node not in section, topic, table, '
+                    'admonition or sidebar'
+                ),
+                location=node,
+            )
             self.visit_rubric(node)
         else:
             try:
@@ -904,9 +918,7 @@ class TexinfoTranslator(SphinxTranslator):
     def visit_enumerated_list(self, node: Element) -> None:
         # doesn't support Roman numerals
         enum = node.get('enumtype', 'arabic')
-        starters = {'arabic': '',
-                    'loweralpha': 'a',
-                    'upperalpha': 'A'}
+        starters = {'arabic': '', 'loweralpha': 'a', 'upperalpha': 'A'}
         start = node.get('start', starters.get(enum, ''))
         self.body.append('\n\n@enumerate %s\n' % start)
 
@@ -1107,8 +1119,7 @@ class TexinfoTranslator(SphinxTranslator):
 
     def depart_admonition(self, node: Element) -> None:
         self.ensure_eol()
-        self.body.append('@end quotation\n'
-                         '@end cartouche\n')
+        self.body.append('@end quotation\n' '@end cartouche\n')
 
     visit_attention = _visit_named_admonition
     depart_attention = depart_admonition
@@ -1194,18 +1205,19 @@ class TexinfoTranslator(SphinxTranslator):
         self.body.append('\n@end float\n\n')
 
     def visit_caption(self, node: Element) -> None:
-        if (isinstance(node.parent, nodes.figure) or
-           (isinstance(node.parent, nodes.container) and
-                node.parent.get('literal_block'))):
+        if isinstance(node.parent, nodes.figure) or (
+            isinstance(node.parent, nodes.container)
+            and node.parent.get('literal_block')
+        ):
             self.body.append('\n@caption{')
         else:
-            logger.warning(__('caption not inside a figure.'),
-                           location=node)
+            logger.warning(__('caption not inside a figure.'), location=node)
 
     def depart_caption(self, node: Element) -> None:
-        if (isinstance(node.parent, nodes.figure) or
-           (isinstance(node.parent, nodes.container) and
-                node.parent.get('literal_block'))):
+        if isinstance(node.parent, nodes.figure) or (
+            isinstance(node.parent, nodes.container)
+            and node.parent.get('literal_block')
+        ):
             self.body.append('}\n')
 
     def visit_image(self, node: Element) -> None:
@@ -1225,8 +1237,7 @@ class TexinfoTranslator(SphinxTranslator):
         height = self.tex_image_length(node.get('height', ''))
         alt = self.escape_arg(node.get('alt', ''))
         filename = f"{self.elements['filename'][:-5]}-figures/{name}"  # type: ignore[index]
-        self.body.append('\n@image{%s,%s,%s,%s,%s}\n' %
-                         (filename, width, height, alt, ext[1:]))
+        self.body.append(f'\n@image{{{filename},{width},{height},{alt},{ext[1:]}}}\n')
 
     def depart_image(self, node: Element) -> None:
         pass
@@ -1268,9 +1279,9 @@ class TexinfoTranslator(SphinxTranslator):
         raise nodes.SkipNode
 
     def visit_system_message(self, node: Element) -> None:
-        self.body.append('\n@verbatim\n'
-                         '<SYSTEM MESSAGE: %s>\n'
-                         '@end verbatim\n' % node.astext())
+        self.body.append(
+            '\n@verbatim\n' '<SYSTEM MESSAGE: %s>\n' '@end verbatim\n' % node.astext()
+        )
         raise nodes.SkipNode
 
     def visit_comment(self, node: Element) -> None:
@@ -1286,8 +1297,7 @@ class TexinfoTranslator(SphinxTranslator):
         self.body.append('<<')
 
     def unimplemented_visit(self, node: Element) -> None:
-        logger.warning(__("unimplemented node type: %r"), node,
-                       location=node)
+        logger.warning(__('unimplemented node type: %r'), node, location=node)
 
     def unknown_departure(self, node: Node) -> None:
         pass
@@ -1336,7 +1346,7 @@ class TexinfoTranslator(SphinxTranslator):
             self.ensure_eol()
         else:
             self.body.append('\n')
-        for (_entry_type, value, _target_id, _main, _category_key) in node['entries']:
+        for _entry_type, value, _target_id, _main, _category_key in node['entries']:
             text = self.escape_menu(value)
             self.body.append('@geindex %s\n' % text)
 
@@ -1362,8 +1372,7 @@ class TexinfoTranslator(SphinxTranslator):
         raise nodes.SkipNode
 
     def visit_seealso(self, node: Element) -> None:
-        self.body.append('\n\n@subsubheading %s\n\n' %
-                         admonitionlabels['seealso'])
+        self.body.append('\n\n@subsubheading %s\n\n' % admonitionlabels['seealso'])
 
     def depart_seealso(self, node: Element) -> None:
         self.body.append('\n')
@@ -1410,8 +1419,9 @@ class TexinfoTranslator(SphinxTranslator):
         # use the full name of the objtype for the category
         try:
             domain = self.builder.env.get_domain(node.parent['domain'])
-            name = domain.get_type_name(domain.object_types[objtype],
-                                        self.config.primary_domain == domain.name)
+            name = domain.get_type_name(
+                domain.object_types[objtype], self.config.primary_domain == domain.name
+            )
         except (KeyError, ExtensionError):
             name = objtype
         # by convention, the deffn category should be capitalized like a title
@@ -1421,7 +1431,7 @@ class TexinfoTranslator(SphinxTranslator):
         self.desc_type_name: str | None = name
 
     def depart_desc_signature(self, node: Element) -> None:
-        self.body.append("\n")
+        self.body.append('\n')
         self.escape_hyphens -= 1
         self.desc_type_name = None
 
@@ -1511,8 +1521,9 @@ class TexinfoTranslator(SphinxTranslator):
         #     -- instead of --
         #     @deffn {Class} class Foo
         txt = node.astext().strip()
-        if ((self.descs and txt == self.descs[-1]['objtype']) or
-                (self.desc_type_name and txt in self.desc_type_name.split())):
+        if (self.descs and txt == self.descs[-1]['objtype']) or (
+            self.desc_type_name and txt in self.desc_type_name.split()
+        ):
             raise nodes.SkipNode
 
     def depart_desc_annotation(self, node: Element) -> None:
@@ -1575,6 +1586,7 @@ class TexinfoTranslator(SphinxTranslator):
     def visit_math_block(self, node: Element) -> None:
         if node.get('label'):
             self.add_anchor(node['label'], node)
-        self.body.append('\n\n@example\n%s\n@end example\n\n' %
-                         self.escape_arg(node.astext()))
+        self.body.append(
+            f'\n\n@example\n{self.escape_arg(node.astext())}\n@end example\n\n'
+        )
         raise nodes.SkipNode