Allow omitting default values (#56)

Author: berhoel

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.10.0
+
+- Add the option to override the generated `default` part of the CLI parameter description.
+
 ## 1.9.0
 
 - Add the option to override the description using the `description` attribute of the directive

README.md

@@ -33,13 +33,14 @@ 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) when provided, overwrites the `<prog>` name.                                                                                                                          |                                                                                                                     |
+| 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}` |
+| no_default_values      | (optional) supresses generation of `default` entries                                                                                                                             |
 
 For example:
 

roots/test-default-handling/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-default-handling/index.rst

@@ -0,0 +1,5 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: main
+  :no_default_values:
+  :hook:

roots/test-default-handling/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def main() -> None:
+    parser = ArgumentParser(prog="foo", add_help=False)
+    parser.add_argument("x", default=1, help="arg (default: True)")
+    args = parser.parse_args()
+    print(args)

src/sphinx_argparse_cli/_logic.py

@@ -68,6 +68,7 @@ class SphinxArgparseCli(SphinxDirective):
         "usage_width": positive_int,
         "group_title_prefix": unchanged,
         "group_sub_title_prefix": unchanged,
+        "no_default_values": unchanged,
     }
 
     def __init__(
@@ -231,7 +232,8 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:
             for content in cast(paragraph, temp.children[0]).children:
                 line += content
         if (
-            action.default != SUPPRESS
+            "no_default_values" not in self.options
+            and action.default != SUPPRESS
             and not re.match(r".*[ (]default[s]? .*", (action.help or ""))
             and not isinstance(action, (_StoreTrueAction, _StoreFalseAction))
         ):

tests/test_logic.py

@@ -233,3 +233,21 @@ def test_lower_upper_refs(build_outcome: str, warning: StringIO) -> None:
     assert '<p id="basic--d"><a class="reference internal" href="#basic--d" title="basic -d">' in build_outcome
     assert '<p id="basic--D"><a class="reference internal" href="#basic--D" title="basic -D">' in build_outcome
     assert not warning.getvalue()
+
+
+@pytest.mark.sphinx(buildername="text", testroot="default-handling")
+def test_with_default(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """foo - CLI interface
+*******************
+
+   foo x
+
+
+foo positional arguments
+========================
+
+* **"x"** - arg (default: True)
+"""
+    )