First version

Signed-off-by: Bernát Gábor <[email protected]>

Author: gaborbernat

.pre-commit-config.yaml

@@ -30,9 +30,15 @@ repos:
   - repo: https://github.com/tox-dev/tox-ini-fmt
     rev: "0.5.0"
     hooks:
-    - id: tox-ini-fmt
+      - id: tox-ini-fmt
   - repo: https://github.com/PyCQA/flake8
     rev: "3.8.4"
     hooks:
       - id: flake8
-        additional_dependencies: ["flake8-bugbear == 20.1.4"]
+        additional_dependencies: [
+            "flake8-bugbear == 20.11.1",
+            "flake8-unused-arguments == 0.0.6",
+            "flake8-comprehensions == 3.3.1",
+            "flake8-spellcheck == 0.23.0",
+            "flake8-pytest-style == 1.3.0",
+        ]

CHANGELOG.md

@@ -2,6 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## unreleased
+## 1.0.0 (2021-02-05)
 
 - First version.

README.md

@@ -10,8 +10,35 @@
 [![Code style:
 black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black)
 
-Render CLI arguments (sub-commands friendly) defined by argparse module.
+Render CLI arguments (sub-commands friendly) defined by the argparse module.
+
+Demo projects:
+
+- [tox](https://tox.readthedocs.io/en/rewrite/cli_interface.html)
 
 ## installation
 
-`pip install sphinx-argparse-cli`
+```bash
+python -m pip install sphinx-argparse-cli
+```
+
+## enable in your `conf.py`
+
+```python
+# just add it to your list of extensions to load within conf.py
+extensions = ["sphinx_argparse_cli"]
+```
+
+## use
+
+Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes two arguments:
+
+- 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
+
+```rst
+.. sphinx_argparse_cli::
+  :module: a_project.cli
+  :func: build_parser
+```

pyproject.toml

@@ -13,6 +13,12 @@ known_first_party = ["sphinx_argparse_cli"]
 write_to = "src/sphinx_argparse_cli/version.py"
 write_to_template = """
 \"\"\" Version information \"\"\"
+from __future__ import annotations
 
-__version__ = "{version}"
+__version__: str = "{version}"
 """
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore::DeprecationWarning:docutils",
+]

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

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

roots/test-basic/parser.py

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

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

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

roots/test-complex/parser.py

@@ -0,0 +1,35 @@
+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")
+
+    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")
+    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