Parse help text as reStructuredText and escape {`, skip default if help text has default

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

Author: gaborbernat

CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## 1.3.0 (2021-02-13)
 
-- Add support for changing the usage width
+- Add support for changing the usage width via the `usage_width` option on the directive
+- Mark document as always needs update (as the underlying content is coming from outside the sphinx documents)
+- Help messages is now interpreted as reStructuredText
+- Matching curly braces, single and double quotes in help text will be marked as string literals
+- Help messages containing the ``default(s)`` word do not show the default value (as often this indicates the default is already documented in the help text)
 
 ## 1.2.0 (2021-02-05)
 

src/sphinx_argparse_cli/_logic.py

@@ -12,7 +12,7 @@
     _SubParsersAction,
 )
 from collections import defaultdict, namedtuple
-from typing import Iterator, Set, cast
+from typing import Iterator, cast
 
 from docutils.nodes import (
     Element,
@@ -27,7 +27,7 @@
     section,
     title,
 )
-from docutils.parsers.rst.directives import unchanged, unchanged_required
+from docutils.parsers.rst.directives import positive_int, unchanged, unchanged_required
 from docutils.parsers.rst.states import RSTState, RSTStateMachine
 from docutils.statemachine import StringList
 from sphinx.util.docutils import SphinxDirective
@@ -47,7 +47,7 @@ class SphinxArgparseCli(SphinxDirective):
         "func": unchanged_required,
         "prog": unchanged,
         "title": unchanged,
-        "usage_width": unchanged,
+        "usage_width": positive_int,
     }
 
     def __init__(
@@ -100,6 +100,7 @@ def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
 
     def run(self) -> list[Node]:
         # construct headers
+        self.env.note_reread()  # this document needs to be always updated
         title_text = self.options.get("title", f"{self.parser.prog} - CLI interface").strip()
         if title_text.strip() == "":
             home_section: Element = paragraph()
@@ -162,9 +163,13 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:  # noqa
             line += ref
         point = list_item("", line, ids=[])
         if action.help:
+            help_text = load_help_text(action.help)
+            temp = paragraph()
+            self.state.nested_parse(StringList(help_text.split("\n")), 0, temp)
             line += Text(" - ")
-            line += Text(action.help)
-        if action.default != SUPPRESS:
+            for content in cast(paragraph, temp.children[0]).children:
+                line += content
+        if action.default != SUPPRESS and not re.match(r".*[ (]default[s]? .*", (action.help or "")):
             line += Text(" (default: ")
             line += literal(text=str(action.default).replace(os.getcwd(), "{cwd}"))
             line += Text(")")
@@ -186,10 +191,22 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
         return group_section
 
     def _mk_usage(self, parser: ArgumentParser) -> literal_block:
-        parser.formatter_class = lambda prog: HelpFormatter(prog, width=int(self.options.get("usage_width", 100)))
+        parser.formatter_class = lambda prog: HelpFormatter(prog, width=self.options.get("usage_width", 100))
         texts = parser.format_usage()[len("usage: ") :].splitlines()
         texts = [line if at == 0 else f"{' ' * (len(parser.prog) + 1)}{line.lstrip()}" for at, line in enumerate(texts)]
         return literal_block("", Text("\n".join(texts)))
 
 
+SINGLE_QUOTE = re.compile(r"[']+(.+?)[']+")
+DOUBLE_QUOTE = re.compile(r'["]+(.+?)["]+')
+CURLY_BRACES = re.compile(r"[{](.+?)[}]")
+
+
+def load_help_text(help_text: str) -> str:
+    single_quote = SINGLE_QUOTE.sub("``'\\1'``", help_text)
+    double_quote = DOUBLE_QUOTE.sub('``"\\1"``', single_quote)
+    literal_curly_braces = CURLY_BRACES.sub("``{\\1}``", double_quote)
+    return literal_curly_braces
+
+
 __all__ = ("SphinxArgparseCli",)

tests/conftest.py

@@ -17,3 +17,7 @@ def pytest_report_header(config: Config) -> str:  # noqa: U100
 @pytest.fixture(scope="session", name="rootdir")
 def root_dir() -> path:
     return path(__file__).parent.parent.abspath() / "roots"
+
+
+def pytest_configure(config: Config) -> None:
+    config.addinivalue_line("markers", "prepare")

tests/test_logic.py

@@ -14,11 +14,11 @@ def build_outcome(app: SphinxTestApp, request: SubRequest) -> str:
     prepare_marker = request.node.get_closest_marker("prepare")
     if prepare_marker:
         directive_args: list[str] | None = prepare_marker.kwargs.get("directive_args")
-        if directive_args:
+        if directive_args:  # pragma: no branch
             index = Path(cast(str, app.confdir)) / "index.rst"
-            if not any(i for i in directive_args if i.startswith(":module:")):
+            if not any(i for i in directive_args if i.startswith(":module:")):  # pragma: no branch
                 directive_args.append(":module: parser")
-            if not any(i for i in directive_args if i.startswith(":func:")):
+            if not any(i for i in directive_args if i.startswith(":func:")):  # pragma: no branch
                 directive_args.append(":func: make")
             args = [f"  {i}" for i in directive_args]
             index.write_text(os.linesep.join([".. sphinx_argparse_cli::"] + args))
@@ -73,3 +73,22 @@ def test_usage_width_default(build_outcome: str) -> None:
 @pytest.mark.prepare(directive_args=[":usage_width: 50"])
 def test_usage_width_custom(build_outcome: str) -> None:
     assert "complex second [-h] [--flag] [--root]\n" in build_outcome
+
+
+@pytest.mark.parametrize(
+    ("example", "output"),
+    [
+        ("", ""),
+        ("{", "{"),
+        ('"', '"'),
+        ("'", "'"),
+        ("{a}", "``{a}``"),
+        ('"a"', '``"a"``'),
+        ("'a'", "``'a'``"),
+    ],
+)
+def test_help_loader(example: str, output: str) -> None:
+    from sphinx_argparse_cli._logic import load_help_text  # noqa
+
+    result = load_help_text(example)
+    assert result == output

tox.ini

@@ -78,5 +78,3 @@ commands =
 
 [pytest]
 junit_family = xunit2
-markers =
-    prepare

whitelist.txt

@@ -23,3 +23,4 @@ statemachine
 subparsers
 testroot
 util
+addinivalue