Implement 'title' directive argument (#3)

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

Author: mondeja

README.md

@@ -31,12 +31,14 @@ extensions = ["sphinx_argparse_cli"]
 
 ## use
 
-Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes two arguments:
+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
 
 ```rst
 .. sphinx_argparse_cli::

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

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

roots/test-title-empty/parser.py

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

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

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :title: My own title

roots/test-title-set/parser.py

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

src/sphinx_argparse_cli/_logic.py

@@ -15,6 +15,7 @@
 from typing import Iterator, Set, cast
 
 from docutils.nodes import (
+    Element,
     Node,
     Text,
     bullet_list,
@@ -45,6 +46,7 @@ class SphinxArgparseCli(SphinxDirective):
         "module": unchanged_required,
         "func": unchanged_required,
         "prog": unchanged,
+        "title": unchanged,
     }
 
     def __init__(
@@ -97,8 +99,12 @@ def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
 
     def run(self) -> list[Node]:
         # construct headers
-        title_text = f"{self.parser.prog} - CLI interface"
-        home_section = section("", title("", Text(title_text)), ids=[make_id(title_text)], names=[title_text])
+        title_text = self.options.get("title", f"{self.parser.prog} - CLI interface").strip()
+        if title_text.strip() == "":
+            home_section: Element = paragraph()
+        else:
+            home_section = section("", title("", Text(title_text)), ids=[make_id(title_text)], names=[title_text])
+
         if self.parser.description:
             desc_paragraph = paragraph("", Text(self.parser.description))
             home_section += desc_paragraph

tests/test_logic.py

@@ -25,3 +25,17 @@ def test_prog_as_text(app: SphinxTestApp) -> None:
     app.build()
     outcome = (Path(app.outdir) / "index.txt").read_text()
     assert outcome == "magic - CLI interface\n*********************\n\n   magic\n"
+
+
+@pytest.mark.sphinx("text", testroot="title-set")
+def test_set_title_as_text(app: SphinxTestApp) -> None:
+    app.build()
+    outcome = (Path(app.outdir) / "index.txt").read_text()
+    assert outcome == "My own title\n************\n\n   foo\n"
+
+
+@pytest.mark.sphinx("text", testroot="title-empty")
+def test_empty_title_as_text(app: SphinxTestApp) -> None:
+    app.build()
+    outcome = (Path(app.outdir) / "index.txt").read_text()
+    assert outcome == "   foo\n"