Allow changing the usage width

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

Author: gaborbernat

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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
+
 ## 1.2.0 (2021-02-05)
 
 - Add support for changing (removing) the title via the `title` attribute of the directive.

README.md

@@ -11,7 +11,8 @@
 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 the argparse module. For live demo checkout the documentation of
-[tox](https://tox.readthedocs.io/en/rewrite/cli_interface.html) and [mdpo](https://mdpo.readthedocs.io/en/latest/cli.html#command-line-interfaces).
+[tox](https://tox.readthedocs.io/en/rewrite/cli_interface.html) and
+[mdpo](https://mdpo.readthedocs.io/en/latest/cli.html#command-line-interfaces).
 
 ## installation
 
@@ -30,12 +31,15 @@ extensions = ["sphinx_argparse_cli"]
 
 Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, 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
-- (optional) a program name that overwrites the autodiscovered running argument parser
-- (optional) a `:title:` argument which, when provided, overwrites the `<prog> - CLI interface` title added by default
-  and when empty, will not be included
+| Name        | Description                                                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| module      | the module path to where the parser is defined                                                                                |
+| func        | the module path to where the parser is defined                                                                                |
+| 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                                                     |
+
+For example:
 
 ```rst
 .. sphinx_argparse_cli::

src/sphinx_argparse_cli/_logic.py

@@ -47,6 +47,7 @@ class SphinxArgparseCli(SphinxDirective):
         "func": unchanged_required,
         "prog": unchanged,
         "title": unchanged,
+        "usage_width": unchanged,
     }
 
     def __init__(
@@ -185,7 +186,7 @@ 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=100)
+        parser.formatter_class = lambda prog: HelpFormatter(prog, width=int(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)))

tests/test_logic.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import os
 from pathlib import Path
+from typing import cast
 
 import pytest
 from _pytest.fixtures import SubRequest
@@ -9,39 +11,65 @@
 
 @pytest.fixture()
 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:
+            index = Path(cast(str, app.confdir)) / "index.rst"
+            if not any(i for i in directive_args if i.startswith(":module:")):
+                directive_args.append(":module: parser")
+            if not any(i for i in directive_args if i.startswith(":func:")):
+                directive_args.append(":func: make")
+            args = [f"  {i}" for i in directive_args]
+            index.write_text(os.linesep.join([".. sphinx_argparse_cli::"] + args))
+
+    ext_mapping = {"html": "html", "text": "txt"}
+    sphinx_marker = request.node.get_closest_marker("sphinx")
+    assert sphinx_marker is not None
+    ext = ext_mapping[sphinx_marker.kwargs.get("buildername")]
+
     app.build()
-    ext = {"html": "html", "text": "txt"}
-    ext = ext.get(request.node.get_closest_marker("sphinx").args[0])
-    assert ext is not None
     return (Path(app.outdir) / f"index.{ext}").read_text()
 
 
-@pytest.mark.sphinx("html", testroot="basic")
+@pytest.mark.sphinx(buildername="html", testroot="basic")
 def test_basic_as_html(build_outcome: str) -> None:
     assert build_outcome
 
 
-@pytest.mark.sphinx("text", testroot="complex")
+@pytest.mark.sphinx(buildername="text", testroot="complex")
 def test_complex_as_text(build_outcome: str) -> None:
     expected = (Path(__file__).parent / "complex.txt").read_text()
     assert build_outcome == expected
 
 
-@pytest.mark.sphinx("html", testroot="complex")
+@pytest.mark.sphinx(buildername="html", testroot="complex")
 def test_complex_as_html(build_outcome: str) -> None:
     assert build_outcome
 
 
-@pytest.mark.sphinx("text", testroot="prog")
+@pytest.mark.sphinx(buildername="text", testroot="prog")
 def test_prog_as_text(build_outcome: str) -> None:
     assert build_outcome == "magic - CLI interface\n*********************\n\n   magic\n"
 
 
-@pytest.mark.sphinx("text", testroot="title-set")
+@pytest.mark.sphinx(buildername="text", testroot="title-set")
 def test_set_title_as_text(build_outcome: str) -> None:
     assert build_outcome == "My own title\n************\n\n   foo\n"
 
 
-@pytest.mark.sphinx("text", testroot="title-empty")
+@pytest.mark.sphinx(buildername="text", testroot="title-empty")
 def test_empty_title_as_text(build_outcome: str) -> None:
     assert build_outcome == "   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:
+    assert "complex second [-h] [--flag] [--root] one pos_two\n" in build_outcome
+
+
+@pytest.mark.sphinx(buildername="text", testroot="complex")
+@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

tox.ini

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

whitelist.txt

@@ -1,14 +1,16 @@
 Formattter
-autouse
-subparsers
 autosectionlabel
+autouse
+buildername
+confdir
 desc
 dest
 docutils
 formatter
 fromlist
 func
 lineno
+linesep
 metavar
 nitpicky
 outdir
@@ -18,5 +20,6 @@ prog
 refid
 rst
 statemachine
+subparsers
 testroot
 util