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

sphinx/cmd/make_mode.py

@@ -29,67 +29,70 @@ if TYPE_CHECKING:
     from collections.abc import Sequence
 
 BUILDERS = [
-    ("",      "html",        "to make standalone HTML files"),
-    ("",      "dirhtml",     "to make HTML files named index.html in directories"),
-    ("",      "singlehtml",  "to make a single large HTML file"),
-    ("",      "pickle",      "to make pickle files"),
-    ("",      "json",        "to make JSON files"),
-    ("",      "htmlhelp",    "to make HTML files and an HTML help project"),
-    ("",      "qthelp",      "to make HTML files and a qthelp project"),
-    ("",      "devhelp",     "to make HTML files and a Devhelp project"),
-    ("",      "epub",        "to make an epub"),
-    ("",      "latex",       "to make LaTeX files, you can set PAPER=a4 or PAPER=letter"),
-    ("posix", "latexpdf",    "to make LaTeX and PDF files (default pdflatex)"),
-    ("posix", "latexpdfja",  "to make LaTeX files and run them through platex/dvipdfmx"),
-    ("",      "text",        "to make text files"),
-    ("",      "man",         "to make manual pages"),
-    ("",      "texinfo",     "to make Texinfo files"),
-    ("posix", "info",        "to make Texinfo files and run them through makeinfo"),
-    ("",      "gettext",     "to make PO message catalogs"),
-    ("",      "changes",     "to make an overview of all changed/added/deprecated items"),
-    ("",      "xml",         "to make Docutils-native XML files"),
-    ("",      "pseudoxml",   "to make pseudoxml-XML files for display purposes"),
-    ("",      "linkcheck",   "to check all external links for integrity"),
-    ("",      "doctest",     "to run all doctests embedded in the documentation "
-                             "(if enabled)"),
-    ("",      "coverage",    "to run coverage check of the documentation (if enabled)"),
-    ("",      "clean",       "to remove everything in the build directory"),
+    ('', 'html', 'to make standalone HTML files'),
+    ('', 'dirhtml', 'to make HTML files named index.html in directories'),
+    ('', 'singlehtml', 'to make a single large HTML file'),
+    ('', 'pickle', 'to make pickle files'),
+    ('', 'json', 'to make JSON files'),
+    ('', 'htmlhelp', 'to make HTML files and an HTML help project'),
+    ('', 'qthelp', 'to make HTML files and a qthelp project'),
+    ('', 'devhelp', 'to make HTML files and a Devhelp project'),
+    ('', 'epub', 'to make an epub'),
+    ('', 'latex', 'to make LaTeX files, you can set PAPER=a4 or PAPER=letter'),
+    ('posix', 'latexpdf', 'to make LaTeX and PDF files (default pdflatex)'),
+    ('posix', 'latexpdfja', 'to make LaTeX files and run them through platex/dvipdfmx'),
+    ('', 'text', 'to make text files'),
+    ('', 'man', 'to make manual pages'),
+    ('', 'texinfo', 'to make Texinfo files'),
+    ('posix', 'info', 'to make Texinfo files and run them through makeinfo'),
+    ('', 'gettext', 'to make PO message catalogs'),
+    ('', 'changes', 'to make an overview of all changed/added/deprecated items'),
+    ('', 'xml', 'to make Docutils-native XML files'),
+    ('', 'pseudoxml', 'to make pseudoxml-XML files for display purposes'),
+    ('', 'linkcheck', 'to check all external links for integrity'),
+    (
+        '',
+        'doctest',
+        'to run all doctests embedded in the documentation ' '(if enabled)',
+    ),
+    ('', 'coverage', 'to run coverage check of the documentation (if enabled)'),
+    ('', 'clean', 'to remove everything in the build directory'),
 ]
 
 
 class Make:
-    def __init__(self, srcdir: str, builddir: str, opts: Sequence[str]) -> None:
-        self.srcdir = srcdir
-        self.builddir = builddir
+    def __init__(self, *, source_dir: str, build_dir: str, opts: Sequence[str]) -> None:
+        self.source_dir = source_dir
+        self.build_dir = build_dir
         self.opts = [*opts]
 
-    def builddir_join(self, *comps: str) -> str:
-        return path.join(self.builddir, *comps)
+    def build_dir_join(self, *comps: str) -> str:
+        return path.join(self.build_dir, *comps)
 
     def build_clean(self) -> int:
-        srcdir = path.abspath(self.srcdir)
-        builddir = path.abspath(self.builddir)
-        if not path.exists(self.builddir):
+        source_dir = path.abspath(self.source_dir)
+        build_dir = path.abspath(self.build_dir)
+        if not path.exists(self.build_dir):
             return 0
-        elif not path.isdir(self.builddir):
-            print("Error: %r is not a directory!" % self.builddir)
+        elif not path.isdir(self.build_dir):
+            print('Error: %r is not a directory!' % self.build_dir)
             return 1
-        elif srcdir == builddir:
-            print("Error: %r is same as source directory!" % self.builddir)
+        elif source_dir == build_dir:
+            print('Error: %r is same as source directory!' % self.build_dir)
             return 1
-        elif path.commonpath([srcdir, builddir]) == builddir:
-            print("Error: %r directory contains source directory!" % self.builddir)
+        elif path.commonpath([source_dir, build_dir]) == build_dir:
+            print('Error: %r directory contains source directory!' % self.build_dir)
             return 1
-        print("Removing everything under %r..." % self.builddir)
-        for item in os.listdir(self.builddir):
-            rmtree(self.builddir_join(item))
+        print('Removing everything under %r...' % self.build_dir)
+        for item in os.listdir(self.build_dir):
+            rmtree(self.build_dir_join(item))
         return 0
 
     def build_help(self) -> None:
         if not color_terminal():
             nocolor()
 
-        print(bold("Sphinx v%s" % sphinx.__display_version__))
+        print(bold('Sphinx v%s' % sphinx.__display_version__))
         print("Please use `make %s' where %s is one of" % ((blue('target'),) * 2))
         for osname, bname, description in BUILDERS:
             if not osname or os.name == osname:
@@ -105,8 +108,40 @@ class Make:
         if not makecmd.lower().startswith('make'):
             raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
-            with chdir(self.builddir_join('latex')):
-                return subprocess.call([makecmd, 'all-pdf'])
+            with chdir(self.build_dir_join('latex')):
+                if '-Q' in self.opts:
+                    with open('__LATEXSTDOUT__', 'w') as outfile:
+                        returncode = subprocess.call(
+                            [
+                                makecmd,
+                                'all-pdf',
+                                'LATEXOPTS=-halt-on-error',
+                            ],
+                            stdout=outfile,
+                            stderr=subprocess.STDOUT,
+                        )
+                    if returncode:
+                        print(
+                            'Latex error: check %s'
+                            % self.build_dir_join('latex', '__LATEXSTDOUT__')
+                        )
+                elif '-q' in self.opts:
+                    returncode = subprocess.call(
+                        [
+                            makecmd,
+                            'all-pdf',
+                            'LATEXOPTS=-halt-on-error',
+                            'LATEXMKOPTS=-silent',
+                        ],
+                    )
+                    if returncode:
+                        print(
+                            'Latex error: check .log file in %s'
+                            % self.build_dir_join('latex')
+                        )
+                else:
+                    returncode = subprocess.call([makecmd, 'all-pdf'])
+                return returncode
         except OSError:
             print('Error: Failed to run: %s' % makecmd)
             return 1
@@ -121,7 +156,7 @@ class Make:
         if not makecmd.lower().startswith('make'):
             raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
-            with chdir(self.builddir_join('latex')):
+            with chdir(self.build_dir_join('latex')):
                 return subprocess.call([makecmd, 'all-pdf'])
         except OSError:
             print('Error: Failed to run: %s' % makecmd)
@@ -136,41 +171,49 @@ class Make:
         if not makecmd.lower().startswith('make'):
             raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
-            with chdir(self.builddir_join('texinfo')):
+            with chdir(self.build_dir_join('texinfo')):
                 return subprocess.call([makecmd, 'info'])
         except OSError:
             print('Error: Failed to run: %s' % makecmd)
             return 1
 
     def build_gettext(self) -> int:
-        dtdir = self.builddir_join('gettext', '.doctrees')
+        dtdir = self.build_dir_join('gettext', '.doctrees')
         if self.run_generic_build('gettext', doctreedir=dtdir) > 0:
             return 1
         return 0
 
     def run_generic_build(self, builder: str, doctreedir: str | None = None) -> int:
         # compatibility with old Makefile
-        papersize = os.getenv('PAPER', '')
-        opts = self.opts
-        if papersize in ('a4', 'letter'):
-            opts.extend(['-D', 'latex_elements.papersize=' + papersize + 'paper'])
+        paper_size = os.getenv('PAPER', '')
+        if paper_size in {'a4', 'letter'}:
+            self.opts.extend(['-D', f'latex_elements.papersize={paper_size}paper'])
         if doctreedir is None:
-            doctreedir = self.builddir_join('doctrees')
+            doctreedir = self.build_dir_join('doctrees')
 
-        args = ['-b', builder,
-                '-d', doctreedir,
-                self.srcdir,
-                self.builddir_join(builder)]
-        return build_main(args + opts)
+        args = [
+            '--builder',
+            builder,
+            '--doctree-dir',
+            doctreedir,
+            self.source_dir,
+            self.build_dir_join(builder),
+        ]
+        return build_main(args + self.opts)
 
 
 def run_make_mode(args: Sequence[str]) -> int:
     if len(args) < 3:
-        print('Error: at least 3 arguments (builder, source '
-              'dir, build dir) are required.', file=sys.stderr)
+        print(
+            'Error: at least 3 arguments (builder, source '
+            'dir, build dir) are required.',
+            file=sys.stderr,
+        )
         return 1
-    make = Make(args[1], args[2], args[3:])
-    run_method = 'build_' + args[0]
+
+    builder_name = args[0]
+    make = Make(source_dir=args[1], build_dir=args[2], opts=args[3:])
+    run_method = f'build_{builder_name}'
     if hasattr(make, run_method):
         return getattr(make, run_method)()
-    return make.run_generic_build(args[0])
+    return make.run_generic_build(builder_name)