Add option to override description (#45)

* Add option to override description

* Update changelog

* Update CHANGELOG.md

Author: Schamper

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.9.0
+
+- Add the option to override the description using the `description` attribute of the directive
+- Add the option to retrieve the arguments by hooking argparse, in cases where `func` consumes the arguments
+  and does not return them
+
 ## 1.8.2
 
 - Don't raise label clashing warnings for options which only differ between upper and lower case

README.md

@@ -33,9 +33,10 @@ Within the reStructuredText files use the `sphinx_argparse_cli` directive that t
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | module                 | the module path to where the parser is defined                                                                                                                                   |
 | func                   | the name of the function that once called with no arguments constructs the parser                                                                                                |
-| prog                   | (optional) the module path to where the parser is defined                                                                                                                        |
+| prog                   | (optional) when provided, overwrites the `<prog>` name.                                                                                                                          |                                                                                                                     |
 | hook                   | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it.                                                                               |
 | title                  | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included                                                    |
+| description            | (optional) when provided, overwrites the description and when empty, will not be included                                                                                        |
 | usage_width            | (optional) how large should usage examples be - defaults to 100 character                                                                                                        |
 | group_title_prefix     | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}`                                           |
 | group_sub_title_prefix | (optional) subcommands groups subsections title prefixes, accepts replacement of `{prog}` and `{subcommand}` for program and subcommand name - defaults to `{prog} {subcommand}` |

roots/test-description-empty/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-description-empty/index.rst

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

roots/test-description-empty/parser.py

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

roots/test-description-set/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-description-set/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :description: My own description

roots/test-description-set/parser.py

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

src/sphinx_argparse_cli/_logic.py

@@ -64,6 +64,7 @@ class SphinxArgparseCli(SphinxDirective):
         "hook": flag,
         "prog": unchanged,
         "title": unchanged,
+        "description": unchanged,
         "usage_width": positive_int,
         "group_title_prefix": unchanged,
         "group_sub_title_prefix": unchanged,
@@ -143,8 +144,9 @@ def run(self) -> list[Node]:
         else:
             home_section = section("", title("", Text(title_text)), ids=[make_id(title_text)], names=[title_text])
 
-        if self.parser.description:
-            desc_paragraph = paragraph("", Text(self.parser.description))
+        description = self.options.get("description", self.parser.description)
+        if description:
+            desc_paragraph = paragraph("", Text(description))
             home_section += desc_paragraph
         # construct groups excluding sub-parsers
         home_section += self._mk_usage(self.parser)

tests/test_logic.py

@@ -86,6 +86,16 @@ def test_empty_title_as_text(build_outcome: str) -> None:
     assert build_outcome == "   foo\n"
 
 
+@pytest.mark.sphinx(buildername="text", testroot="description-set")
+def test_set_description_as_text(build_outcome: str) -> None:
+    assert build_outcome == "foo - CLI interface\n*******************\n\nMy own description\n\n   foo\n"
+
+
+@pytest.mark.sphinx(buildername="text", testroot="description-empty")
+def test_empty_description_as_text(build_outcome: str) -> None:
+    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
+
+
 @pytest.mark.sphinx(buildername="text", testroot="complex")
 @pytest.mark.prepare(directive_args=[":usage_width: 100"])
 def test_usage_width_default(build_outcome: str) -> None: