Consolidate sys.argv handling

CHANGES

@@ -57,6 +57,7 @@ Features added
   text elements nodes. See :doc:`the documentation </extdev/nodes>` for more
   details.
   Patch by Bénédikt Tran.
+* Allow running Sphinx with ``python -m sphinx build ...``.
 
 Bugs fixed
 ----------

sphinx/__main__.py

@@ -1,5 +1,7 @@
 """The Sphinx documentation toolchain."""
 
+import sys
+
 from sphinx.cmd.build import main
 
-raise SystemExit(main())
+raise SystemExit(main(sys.argv[1:]))

sphinx/cmd/build.py

@@ -204,13 +204,13 @@ def get_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def make_main(argv: list[str] = sys.argv[1:]) -> int:
+def make_main(argv: list[str]) -> int:
     """Sphinx build "make mode" entry."""
     from sphinx.cmd import make_mode
     return make_mode.run_make_mode(argv[1:])
 
 
-def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
+def _parse_arguments(argv: list[str]) -> argparse.Namespace:
     parser = get_parser()
     args = parser.parse_args(argv)
 
@@ -279,7 +279,7 @@ def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
     return args
 
 
-def build_main(argv: list[str] = sys.argv[1:]) -> int:
+def build_main(argv: list[str]) -> int:
     """Sphinx build "main" command-line entry."""
     args = _parse_arguments(argv)
 
@@ -319,17 +319,19 @@ def _bug_report_info() -> int:
     return 0
 
 
-def main(argv: list[str] = sys.argv[1:]) -> int:
+def main(argv: list[str], /) -> int:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
     if argv[:1] == ['--bug-report']:
         return _bug_report_info()
     if argv[:1] == ['-M']:
         return make_main(argv)
+    elif argv[:1] == ['build']:
+        return build_main(argv[1:])
     else:
         return build_main(argv)
 
 
 if __name__ == '__main__':
-    raise SystemExit(main())
+    raise SystemExit(main(sys.argv[1:]))

sphinx/cmd/quickstart.py

@@ -545,7 +545,7 @@ def get_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] = sys.argv[1:]) -> int:
+def main(argv: list[str], /) -> int:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
@@ -611,4 +611,4 @@ def main(argv: list[str] = sys.argv[1:]) -> int:
 
 
 if __name__ == '__main__':
-    raise SystemExit(main())
+    raise SystemExit(main(sys.argv[1:]))

sphinx/ext/apidoc.py

@@ -409,7 +409,7 @@ def get_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] = sys.argv[1:]) -> int:
+def main(argv: list[str], /) -> int:
     """Parse and check the command line arguments."""
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
@@ -489,4 +489,4 @@ def main(argv: list[str] = sys.argv[1:]) -> int:
 
 # So program can be started with "python -m sphinx.apidoc ..."
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main(sys.argv[1:]))

sphinx/ext/autosummary/generate.py

@@ -729,7 +729,7 @@ def get_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] = sys.argv[1:]) -> None:
+def main(argv: list[str], /) -> None:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
@@ -751,4 +751,4 @@ def main(argv: list[str] = sys.argv[1:]) -> None:
 
 
 if __name__ == '__main__':
-    main()
+    main(sys.argv[1:])

sphinx/ext/intersphinx.py

@@ -698,13 +698,13 @@ def setup(app: Sphinx) -> dict[str, Any]:
     }
 
 
-def inspect_main(argv: list[str]) -> None:
+def inspect_main(argv: list[str], /) -> int:
     """Debug functionality to print out an inventory"""
     if len(argv) < 1:
         print("Print out an inventory file.\n"
               "Error: must specify local path or URL to an inventory file.",
               file=sys.stderr)
-        raise SystemExit(1)
+        return 1
 
     class MockConfig:
         intersphinx_timeout: int | None = None
@@ -716,26 +716,27 @@ class MockApp:
         srcdir = ''
         config = MockConfig()
 
-        def warn(self, msg: str) -> None:
-            print(msg, file=sys.stderr)
-
     try:
         filename = argv[0]
-        invdata = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
-        for key in sorted(invdata or {}):
+        inv_data: Inventory = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
+        for key in sorted(inv_data or {}):
             print(key)
-            for entry, einfo in sorted(invdata[key].items()):
-                print('\t%-40s %s%s' % (entry,
-                                        '%-40s: ' % einfo[3] if einfo[3] != '-' else '',
-                                        einfo[2]))
+            inv_entries = sorted(inv_data[key].items())
+            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
+                display_name = display_name * (display_name != '-')
+                print(f'    {entry:<40} {display_name:<40}: {url_path}')
     except ValueError as exc:
-        print(exc.args[0] % exc.args[1:])
+        print(exc.args[0] % exc.args[1:], file=sys.stderr)
+        return 1
     except Exception as exc:
-        print('Unknown error: %r' % exc)
+        print(f'Unknown error: {exc!r}', file=sys.stderr)
+        return 1
+    else:
+        return 0
 
 
 if __name__ == '__main__':
     import logging as _logging
     _logging.basicConfig()
 
-    inspect_main(argv=sys.argv[1:])
+    raise SystemExit(inspect_main(sys.argv[1:]))