Add option to especify 'prog' (#1)

Author: mondeja

README.md

@@ -36,9 +36,11 @@ Within the reStructuredText files use the `sphinx_argparse_cli` directive that t
 - the module path to where the parser is defined,
 - a no argument function within that module that once called returns the constructed
   [argparse](https://docs.python.org/3/library/argparse.html) parser
+- (optional) a program name that overwrites the autodiscovered running argument parser
 
 ```rst
 .. sphinx_argparse_cli::
   :module: a_project.cli
   :func: build_parser
+  :prog: my-cli-program
 ```

roots/test-prog/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-prog/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :prog: magic

roots/test-prog/parser.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    return ArgumentParser(add_help=False)

src/sphinx_argparse_cli/_logic.py

@@ -26,7 +26,7 @@
     section,
     title,
 )
-from docutils.parsers.rst.directives import unchanged_required
+from docutils.parsers.rst.directives import unchanged, unchanged_required
 from docutils.parsers.rst.states import RSTState, RSTStateMachine
 from docutils.statemachine import StringList
 from sphinx.util.docutils import SphinxDirective
@@ -41,7 +41,11 @@ def make_id(key: str) -> str:
 class SphinxArgparseCli(SphinxDirective):
     name = "sphinx_argparse_cli"
     has_content = False
-    option_spec = {"module": unchanged_required, "func": unchanged_required}
+    option_spec = {
+        "module": unchanged_required,
+        "func": unchanged_required,
+        "prog": unchanged,
+    }
 
     def __init__(
         self,
@@ -64,6 +68,8 @@ def parser(self) -> ArgumentParser:
             module_name, attr_name = self.options["module"], self.options["func"]
             parser_creator = getattr(__import__(module_name, fromlist=[attr_name]), attr_name)
             self._parser = parser_creator()
+            if "prog" in self.options:
+                self._parser.prog = self.options["prog"]
             del sys.modules[module_name]  # no longer needed cleanup
         return self._parser
 

tests/test_logic.py

@@ -7,14 +7,21 @@
 
 
 @pytest.mark.sphinx("html", testroot="basic")
-def test_basic_as_text(app: SphinxTestApp) -> None:
+def test_basic_as_html(app: SphinxTestApp) -> None:
     app.build()
     outcome = (Path(app.outdir) / "index.html").read_text()
     assert outcome
 
 
 @pytest.mark.sphinx("html", testroot="complex")
-def test_complex_as_text(app: SphinxTestApp) -> None:
+def test_complex_as_html(app: SphinxTestApp) -> None:
     app.build()
     outcome = (Path(app.outdir) / "index.html").read_text()
     assert outcome
+
+
+@pytest.mark.sphinx("text", testroot="prog")
+def test_prog_as_text(app: SphinxTestApp) -> None:
+    app.build()
+    outcome = (Path(app.outdir) / "index.txt").read_text()
+    assert outcome == "magic - CLI interface\n*********************\n\n   magic\n"