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

sphinx/builders/texinfo.py

@@ -25,7 +25,7 @@ from sphinx.util.osutil import SEP, copyfile, ensuredir, make_filename_from_proj
 from sphinx.writers.texinfo import TexinfoTranslator, TexinfoWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Set
 
     from docutils.nodes import Node
 
@@ -46,12 +46,13 @@ class TexinfoBuilder(Builder):
     format = 'texinfo'
     epilog = __('The Texinfo files are in %(outdir)s.')
     if os.name == 'posix':
-        epilog += __("\nRun 'make' in that directory to run these through "
-                     "makeinfo\n"
-                     "(use 'make info' here to do that automatically).")
+        epilog += __(
+            "\nRun 'make' in that directory to run these through "
+            'makeinfo\n'
+            "(use 'make info' here to do that automatically)."
+        )
 
-    supported_image_types = ['image/png', 'image/jpeg',
-                             'image/gif']
+    supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
     default_translator_class = TexinfoTranslator
 
     def init(self) -> None:
@@ -70,28 +71,34 @@ class TexinfoBuilder(Builder):
         # ignore source path
         return self.get_target_uri(to, typ)
 
-    def init_document_data(self) -> None:
+    def prepare_writing(self, _docnames: Set[str]) -> None:
         preliminary_document_data = [list(x) for x in self.config.texinfo_documents]
         if not preliminary_document_data:
-            logger.warning(__('no "texinfo_documents" config value found; no documents '
-                              'will be written'))
+            logger.warning(
+                __(
+                    'no "texinfo_documents" config value found; no documents '
+                    'will be written'
+                )
+            )
             return
         # assign subdirs to titles
         self.titles: list[tuple[str, str]] = []
         for entry in preliminary_document_data:
             docname = entry[0]
             if docname not in self.env.all_docs:
-                logger.warning(__('"texinfo_documents" config value references unknown '
-                                  'document %s'), docname)
+                logger.warning(
+                    __(
+                        '"texinfo_documents" config value references unknown '
+                        'document %s'
+                    ),
+                    docname,
+                )
                 continue
             self.document_data.append(entry)  # type: ignore[arg-type]
-            if docname.endswith(SEP + 'index'):
-                docname = docname[:-5]
+            docname = docname.removesuffix(SEP + 'index')
             self.titles.append((docname, entry[2]))
 
-    def write(self, *ignored: Any) -> None:
-        self.init_document_data()
-        self.copy_assets()
+    def write_documents(self, _docnames: Set[str]) -> None:
         for entry in self.document_data:
             docname, targetname, title, author = entry[:4]
             targetname += '.texi'
@@ -102,13 +109,15 @@ class TexinfoBuilder(Builder):
             if len(entry) > 7:
                 toctree_only = entry[7]
             destination = FileOutput(
-                destination_path=path.join(self.outdir, targetname),
-                encoding='utf-8')
-            with progress_message(__("processing %s") % targetname):
+                destination_path=path.join(self.outdir, targetname), encoding='utf-8'
+            )
+            with progress_message(__('processing %s') % targetname, nonl=False):
                 appendices = self.config.texinfo_appendices or []
-                doctree = self.assemble_doctree(docname, toctree_only, appendices=appendices)
+                doctree = self.assemble_doctree(
+                    docname, toctree_only, appendices=appendices
+                )
 
-            with progress_message(__("writing")):
+            with progress_message(__('writing')):
                 self.post_process_images(doctree)
                 docwriter = TexinfoWriter(self)
                 with warnings.catch_warnings():
@@ -118,7 +127,8 @@ class TexinfoBuilder(Builder):
                     settings: Any = OptionParser(
                         defaults=self.env.settings,
                         components=(docwriter,),
-                        read_config_files=True).get_default_values()
+                        read_config_files=True,
+                    ).get_default_values()
                 settings.author = author
                 settings.title = title
                 settings.texinfo_filename = targetname[:-5] + '.info'
@@ -132,10 +142,13 @@ class TexinfoBuilder(Builder):
                 self.copy_image_files(targetname[:-5])
 
     def assemble_doctree(
-        self, indexfile: str, toctree_only: bool, appendices: list[str],
+        self,
+        indexfile: str,
+        toctree_only: bool,
+        appendices: list[str],
     ) -> nodes.document:
         self.docnames = {indexfile, *appendices}
-        logger.info(darkgreen(indexfile) + " ", nonl=True)
+        logger.info(darkgreen(indexfile))
         tree = self.env.get_doctree(indexfile)
         tree['docname'] = indexfile
         if toctree_only:
@@ -143,21 +156,21 @@ class TexinfoBuilder(Builder):
             # fresh document
             new_tree = new_document('<texinfo output>')
             new_sect = nodes.section()
-            new_sect += nodes.title('<Set title in conf.py>',
-                                    '<Set title in conf.py>')
+            new_sect += nodes.title('<Set title in conf.py>', '<Set title in conf.py>')
             new_tree += new_sect
             for node in tree.findall(addnodes.toctree):
                 new_sect += node
             tree = new_tree
-        largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
-                                        darkgreen, [indexfile])
+        largetree = inline_all_toctrees(
+            self, self.docnames, indexfile, tree, darkgreen, [indexfile]
+        )
         largetree['docname'] = indexfile
         for docname in appendices:
             appendix = self.env.get_doctree(docname)
             appendix['docname'] = docname
             largetree.append(appendix)
         logger.info('')
-        logger.info(__("resolving references..."))
+        logger.info(__('resolving references...'))
         self.env.resolve_references(largetree, indexfile, self)
         # TODO: add support for external :ref:s
         for pendingnode in largetree.findall(addnodes.pending_xref):
@@ -183,9 +196,14 @@ class TexinfoBuilder(Builder):
     def copy_image_files(self, targetname: str) -> None:
         if self.images:
             stringify_func = ImageAdapter(self.app.env).get_original_image_uri
-            for src in status_iterator(self.images, __('copying images... '), "brown",
-                                       len(self.images), self.app.verbosity,
-                                       stringify_func=stringify_func):
+            for src in status_iterator(
+                self.images,
+                __('copying images... '),
+                'brown',
+                len(self.images),
+                self.app.verbosity,
+                stringify_func=stringify_func,
+            ):
                 dest = self.images[src]
                 try:
                     imagedir = self.outdir / f'{targetname}-figures'
@@ -196,8 +214,11 @@ class TexinfoBuilder(Builder):
                         force=True,
                     )
                 except Exception as err:
-                    logger.warning(__('cannot copy image file %r: %s'),
-                                   path.join(self.srcdir, src), err)
+                    logger.warning(
+                        __('cannot copy image file %r: %s'),
+                        path.join(self.srcdir, src),
+                        err,
+                    )
 
     def copy_support_files(self) -> None:
         try:
@@ -209,7 +230,7 @@ class TexinfoBuilder(Builder):
                     force=True,
                 )
         except OSError as err:
-            logger.warning(__("error writing file Makefile: %s"), err)
+            logger.warning(__('error writing file Makefile: %s'), err)
 
 
 def default_texinfo_documents(
@@ -217,8 +238,17 @@ def default_texinfo_documents(
 ) -> list[tuple[str, str, str, str, str, str, str]]:
     """Better default texinfo_documents settings."""
     filename = make_filename_from_project(config.project)
-    return [(config.root_doc, filename, config.project, config.author, filename,
-             'One line description of project', 'Miscellaneous')]
+    return [
+        (
+            config.root_doc,
+            filename,
+            config.project,
+            config.author,
+            filename,
+            'One line description of project',
+            'Miscellaneous',
+        )
+    ]
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/builders/text.py

@@ -18,9 +18,9 @@ from sphinx.util.osutil import (
 from sphinx.writers.text import TextTranslator, TextWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
-    from docutils.nodes import Node
+    from docutils import nodes
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
@@ -64,10 +64,10 @@ class TextBuilder(Builder):
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return ''
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         self.writer = TextWriter(self)
 
-    def write_doc(self, docname: str, doctree: Node) -> None:
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
         self.current_docname = docname
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
         destination = StringOutput(encoding='utf-8')
@@ -78,7 +78,7 @@ class TextBuilder(Builder):
             with open(outfilename, 'w', encoding='utf-8') as f:
                 f.write(self.writer.output)
         except OSError as err:
-            logger.warning(__("error writing file %s: %s"), outfilename, err)
+            logger.warning(__('error writing file %s: %s'), outfilename, err)
 
     def finish(self) -> None:
         pass

sphinx/builders/xml.py

@@ -20,9 +20,7 @@ from sphinx.util.osutil import (
 from sphinx.writers.xml import PseudoXMLWriter, XMLWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-    from docutils.nodes import Node
+    from collections.abc import Iterator, Set
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
@@ -70,16 +68,15 @@ class XMLBuilder(Builder):
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return docname
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         self.writer = self._writer_class(self)
 
-    def write_doc(self, docname: str, doctree: Node) -> None:
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
         # work around multiple string % tuple issues in docutils;
         # replace tuples in attribute values with lists
         doctree = doctree.deepcopy()
-        for domain in self.env.domains.values():
-            xmlns = "xmlns:" + domain.name
-            doctree[xmlns] = "https://www.sphinx-doc.org/"  # type: ignore[index]
+        for domain in self.env.domains.sorted():
+            doctree[f'xmlns:{domain.name}'] = 'https://www.sphinx-doc.org/'
         for node in doctree.findall(nodes.Element):
             for att, value in node.attributes.items():
                 if isinstance(value, tuple):
@@ -97,7 +94,7 @@ class XMLBuilder(Builder):
             with open(outfilename, 'w', encoding='utf-8') as f:
                 f.write(self.writer.output)
         except OSError as err:
-            logger.warning(__("error writing file %s: %s"), outfilename, err)
+            logger.warning(__('error writing file %s: %s'), outfilename, err)
 
     def finish(self) -> None:
         pass