Add custom subsection group prefix title support (#12)

Co-authored-by: Bernát Gábor <[email protected]>

Author: mondeja

README.md

@@ -31,13 +31,15 @@ extensions = ["sphinx_argparse_cli"]
 
 Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:
 
-| Name        | Description                                                                                                                   |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| 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                                                                     |
-| title       | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included |
-| usage_width | (optional) how large should usage examples be - defaults to 100 character                                                     |
+| Name                   | Description                                                                                                                                                                      |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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                                                                                                                        |
+| title                  | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default 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}` |
 
 For example:
 

roots/test-group-title-empty-prefixes/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-group-title-empty-prefixes/index.rst

@@ -0,0 +1,5 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_title_prefix:
+  :group_sub_title_prefix:

roots/test-group-title-empty-prefixes/parser.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="complex")
+    parser.add_argument("--root", action="store_true", help="root flag")
+    parser.add_argument("--no-help", action="store_true")
+    parser.add_argument("--outdir", "-o", type=str, help="output directory", metavar="out_dir")
+    parser.add_argument("--in-dir", "-i", type=str, help="input directory", dest="in_dir")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+
+    sub_parsers_a.add_parser("third")  # empty sub-command
+    return parser

roots/test-group-title-prefix-custom-subcommands/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-group-title-prefix-custom-subcommands/index.rst

@@ -0,0 +1,17 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_sub_title_prefix: custom
+
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_title_prefix:
+  :group_sub_title_prefix: custom-2
+
+
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_title_prefix: myprog
+  :group_sub_title_prefix: custom-3

roots/test-group-title-prefix-custom-subcommands/parser.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="complex")
+    parser.add_argument("--root", action="store_true", help="root flag")
+    parser.add_argument("--no-help", action="store_true")
+    parser.add_argument("--outdir", "-o", type=str, help="output directory", metavar="out_dir")
+    parser.add_argument("--in-dir", "-i", type=str, help="input directory", dest="in_dir")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+
+    sub_parsers_a.add_parser("third")  # empty sub-command
+    return parser

roots/test-group-title-prefix-custom/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-group-title-prefix-custom/index.rst

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

roots/test-group-title-prefix-custom/parser.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="prog")
+    parser.add_argument("root")
+    parser.add_argument("--root", action="store_true", help="root flag")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+    return parser

roots/test-group-title-prefix-default/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-group-title-prefix-default/index.rst

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

roots/test-group-title-prefix-default/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="prog")
+    parser.add_argument("root")
+    parser.add_argument("--root", action="store_true", help="root flag")
+    return parser

roots/test-group-title-prefix-empty-subcommands/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-group-title-prefix-empty-subcommands/index.rst

@@ -0,0 +1,11 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_sub_title_prefix:
+
+
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_title_prefix: myprog
+  :group_sub_title_prefix:

roots/test-group-title-prefix-empty-subcommands/parser.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="complex")
+    parser.add_argument("--root", action="store_true", help="root flag")
+    parser.add_argument("--no-help", action="store_true")
+    parser.add_argument("--outdir", "-o", type=str, help="output directory", metavar="out_dir")
+    parser.add_argument("--in-dir", "-i", type=str, help="input directory", dest="in_dir")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+
+    sub_parsers_a.add_parser("third")  # empty sub-command
+    return parser

roots/test-group-title-prefix-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-group-title-prefix-empty/index.rst

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

roots/test-group-title-prefix-empty/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="prog")
+    parser.add_argument("root")
+    parser.add_argument("--root", action="store_true", help="root flag")
+    return parser

roots/test-group-title-prefix-prog-replacement/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-group-title-prefix-prog-replacement/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_title_prefix: {prog}foo

roots/test-group-title-prefix-prog-replacement/parser.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="bar")
+    parser.add_argument("root")
+    parser.add_argument("--root", action="store_true", help="root flag")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+    return parser

roots/test-group-title-prefix-subcommand-replacement/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-group-title-prefix-subcommand-replacement/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_sub_title_prefix: {prog}only{subcommand}

roots/test-group-title-prefix-subcommand-replacement/parser.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(description="argparse tester", prog="bar")
+    parser.add_argument("root")
+    parser.add_argument("--root", action="store_true", help="root flag")
+
+    group = parser.add_argument_group("Exclusive", description="this is an exclusive group")
+    exclusive = group.add_mutually_exclusive_group()
+    exclusive.add_argument("--foo", action="store_true", help="foo")
+    exclusive.add_argument("--bar", action="store_true", help="bar")
+
+    parser.add_argument_group("empty")
+
+    sub_parsers_a = parser.add_subparsers(title="sub-parser-a", description="sub parsers A", dest="command")
+    sub_parsers_a.required = False
+    sub_parsers_a.default = "first"
+
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
+    a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
+    a_parser_first.add_argument("--root", action="store_true", help="root flag")
+    a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_first.add_argument("pos_two", help="second positional argument", default=1)
+
+    a_parser_second = sub_parsers_a.add_parser("second")
+    a_parser_second.add_argument("--flag", dest="a_par_second_flag", action="store_true", help="a parser second flag")
+    a_parser_second.add_argument("--root", action="store_true", help="root flag")
+    a_parser_second.add_argument("pos_one", help="first positional argument", metavar="one")
+    a_parser_second.add_argument("pos_two", help="second positional argument", default="green")
+    return parser