Implement ability to use ref to refer to content generated

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

Author: gaborbernat

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.6.0 (2021-04-15)
+
+- Support for using the `ref` sphinx role to refer to all anchor-able objects generated by the tool
+- Flags now have their reference title set (for the HTML builder this is shown when hover over the reference)
+- Anchors generated no longer collapse multiple subsequent `-` characters (to avoid clash when there's a flag and a
+  positional argument with the same name)
+- Added a sphinx flag `sphinx_argparse_cli_prefix_document` (by default `False`) to avoid reference clashes when
+  multiple documents generate the same reference labels
+- The root `prog` name now is prefixed for the root level optional/positional arguments' header (to avoid multiple
+  anchors with the same id when multiple commands are documented in the same document)
+
 ## 1.5.1 (2021-04-15)
 
 - For sub-commands use the parser description first as description and only then fallback to the help message

README.md

@@ -47,3 +47,25 @@ For example:
   :func: build_parser
   :prog: my-cli-program
 ```
+
+### Refer to generated content
+
+The tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to
+both the (sub)command title/groups and every flag/argument. The tool offers a configuration flag
+`sphinx_argparse_cli_prefix_document` (change by setting this variable in `conf.py` - by default `False`). This option
+influences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the
+`'#` in the URI once you click on it). If it's true the anchor id will be prefixed by the document name (this is useful
+to avoid reference label clash when the same anchors are generated in multiple documents).
+
+For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):
+
+- to refer to the optional arguments group use `` :ref:`tox-optional-arguments`  ``,
+- to refer to the run subcommand use `` :ref:`tox-run`  ``,
+- to refer to flag `--magic` of the `run` sub-command use `` :ref:`tox-run---magic`  ``.
+
+For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name
+being `cli`:
+
+- to refer to the optional arguments group use `` :ref:`cli:tox-optional-arguments`  ``,
+- to refer to the run subcommand use `` :ref:`cli:tox-run`  ``,
+- to refer to flag `--magic` of the `run` sub-command use `` :ref:`cli:tox-run---magic`  ``.

roots/test-ref-duplicate-label/cli.rst

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

roots/test-ref-duplicate-label/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-ref-duplicate-label/index.rst

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

roots/test-ref-duplicate-label/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-ref-prefix-doc/conf.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True
+sphinx_argparse_cli_prefix_document = True

roots/test-ref-prefix-doc/index.rst

@@ -0,0 +1,7 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+
+Reference test
+--------------
+Flag :ref:`index:prog---root` and positional :ref:`index:prog-root`.

roots/test-ref-prefix-doc/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-ref/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-ref/index.rst

@@ -0,0 +1,7 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+
+Reference test
+--------------
+Flag :ref:`prog---root` and positional :ref:`prog-root`.

roots/test-ref/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

src/sphinx_argparse_cli/__init__.py

@@ -11,6 +11,7 @@ def setup(app: Sphinx) -> None:
     from ._logic import SphinxArgparseCli
 
     app.add_directive(SphinxArgparseCli.name, SphinxArgparseCli)
+    app.add_config_value("sphinx_argparse_cli_prefix_document", False, "env")
 
 
 __all__ = ("__version__",)

src/sphinx_argparse_cli/_logic.py

@@ -3,14 +3,9 @@
 import os
 import re
 import sys
-from argparse import (
-    SUPPRESS,
-    Action,
-    ArgumentParser,
-    HelpFormatter,
-    _ArgumentGroup,
-    _SubParsersAction,
-)
+from argparse import _ArgumentGroup  # noqa
+from argparse import _SubParsersAction  # noqa
+from argparse import SUPPRESS, Action, ArgumentParser, HelpFormatter
 from collections import defaultdict, namedtuple
 from typing import Iterator, cast
 
@@ -19,6 +14,7 @@
     Node,
     Text,
     bullet_list,
+    fully_normalize_name,
     list_item,
     literal,
     literal_block,
@@ -31,13 +27,19 @@
 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.domains.std import StandardDomain
+from sphinx.locale import __
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.logging import getLogger
 
 TextAsDefault = namedtuple("TextAsDefault", ["text"])
 
 
 def make_id(key: str) -> str:
-    return re.sub(r"-{2,}", "-", re.sub(r"\W", "-", key)).rstrip("-").lower()
+    return "-".join(key.split()).rstrip("-").lower()
+
+
+logger = getLogger(__name__)
 
 
 class SphinxArgparseCli(SphinxDirective):
@@ -65,6 +67,7 @@ def __init__(
     ):
         super().__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
         self._parser: ArgumentParser | None = None
+        self._std_domain: StandardDomain = cast(StandardDomain, self.env.get_domain("std"))
 
     @property
     def parser(self) -> ArgumentParser:
@@ -116,7 +119,7 @@ def run(self) -> list[Node]:
         for group in self.parser._action_groups:  # noqa
             if not group._group_actions or group is self.parser._subparsers:  # noqa
                 continue
-            home_section += self._mk_option_group(group, prefix="")
+            home_section += self._mk_option_group(group, prefix=self.parser.prog.split("/")[-1])
         # construct sub-parser
         for aliases, help_msg, parser in self.load_sub_parsers():
             home_section += self._mk_sub_command(aliases, help_msg, parser)
@@ -130,6 +133,7 @@ def _mk_option_group(self, group: _ArgumentGroup, prefix: str) -> section:
         group_section = section("", header, ids=[ref_id], names=[ref_id])
         if group.description:
             group_section += paragraph("", Text(group.description))
+        self._register_ref(ref_id, title_text, group_section)
         opt_group = bullet_list()
         for action in group._group_actions:  # noqa
             point = self._mk_option_line(action, prefix)
@@ -171,21 +175,42 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:  # noqa
             line += Text(")")
         return point
 
-    @staticmethod
-    def _mk_option_name(line: paragraph, prefix: str, opt: str) -> None:
+    def _mk_option_name(self, line: paragraph, prefix: str, opt: str) -> None:
         ref_id = make_id(f"{prefix}-{opt}")
-        ref = reference("", refid=ref_id)
+        ref_title = f"{prefix} {opt}"
+        ref = reference("", refid=ref_id, reftitle=ref_title)
         line.attributes["ids"].append(ref_id)
         st = strong()
         st += literal(text=opt)
         ref += st
+        self._register_ref(ref_id, ref_title, ref)
         line += ref
 
+    def _register_ref(self, ref_name: str, ref_title: str, node: Element) -> None:
+        doc_name = self.env.docname
+        if self.env.config.sphinx_argparse_cli_prefix_document:
+            name = fully_normalize_name(f"{doc_name}:{ref_name}")
+        else:
+            name = fully_normalize_name(ref_name)
+        if name in self._std_domain.labels:
+            logger.warning(
+                __("duplicate label %s, other instance in %s"),
+                name,
+                self.env.doc2path(self._std_domain.labels[name][0]),
+                location=node,
+                type="sphinx-argparse-cli",
+                subtype=self.env.docname,
+            )
+        self._std_domain.anonlabels[name] = doc_name, ref_name
+        self._std_domain.labels[name] = doc_name, ref_name, ref_title
+
     def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentParser) -> section:
         title_text = f"{parser.prog}"
         if aliases:
             title_text += f" ({', '.join(aliases)})"
-        group_section = section("", title("", Text(title_text)), ids=[make_id(title_text)], names=[title_text])
+        ref_id = make_id(title_text)
+        group_section = section("", title("", Text(title_text)), ids=[ref_id], names=[title_text])
+        self._register_ref(ref_id, title_text, group_section)
 
         command_desc = (parser.description or help_msg or "").strip()
         if command_desc:

tests/complex.txt

@@ -7,8 +7,8 @@ argparse tester
            {first,f,second,third} ...
 
 
-optional arguments
-==================
+complex optional arguments
+==========================
 
 * **"-h"**, **"--help"** - show this help message and exit
 
@@ -23,8 +23,8 @@ optional arguments
   (default: "None")
 
 
-Exclusive
-=========
+complex Exclusive
+=================
 
 this is an exclusive group
 

tests/test_logic.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+from io import StringIO
 from pathlib import Path
 from typing import cast
 
@@ -29,7 +30,8 @@ def build_outcome(app: SphinxTestApp, request: SubRequest) -> str:
     ext = ext_mapping[sphinx_marker.kwargs.get("buildername")]
 
     app.build()
-    return (Path(app.outdir) / f"index.{ext}").read_text()
+    text = (Path(app.outdir) / f"index.{ext}").read_text()
+    return text
 
 
 @pytest.mark.sphinx(buildername="html", testroot="basic")
@@ -92,3 +94,33 @@ def test_help_loader(example: str, output: str) -> None:
 
     result = load_help_text(example)
     assert result == output
+
+
+@pytest.mark.sphinx(buildername="html", testroot="ref")
+def test_ref_as_html(build_outcome: str) -> None:
+    ref = (
+        '<p>Flag <a class="reference internal" href="#prog---root"><span class="std std-ref">prog --root</span></a> and'
+        ' positional <a class="reference internal" href="#prog-root"><span class="std std-ref">prog root</span></a>.'
+        "</p>"
+    )
+    assert ref in build_outcome
+
+
+@pytest.mark.sphinx(buildername="html", testroot="ref-prefix-doc")
+def test_ref_prefix_doc(build_outcome: str) -> None:
+    ref = (
+        '<p>Flag <a class="reference internal" href="#prog---root"><span class="std std-ref">prog --root</span></a> and'
+        ' positional <a class="reference internal" href="#prog-root"><span class="std std-ref">prog root</span></a>.'
+        "</p>"
+    )
+    assert ref in build_outcome
+
+
+_REF_WARNING_STRING_IO = StringIO()  # could not find any better way to get the warning
+
+
+@pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label", warning=_REF_WARNING_STRING_IO)
+def test_ref_duplicate_label(build_outcome: tuple[str, str]) -> None:
+    assert build_outcome
+    warnings = _REF_WARNING_STRING_IO.getvalue()
+    assert "duplicate label prog---help" in warnings

tox.ini

@@ -46,7 +46,7 @@ description = run type check on code base
 setenv =
     {tty:MYPY_FORCE_COLOR = 1}
 deps =
-    mypy==0.800
+    mypy==0.812
 commands =
     mypy --strict --python-version 3.9 src
     mypy --strict --python-version 3.9 tests

whitelist.txt

@@ -1,14 +1,16 @@
-Formattter
+addinivalue
+anonlabels
 autosectionlabel
-autouse
 buildername
 confdir
 desc
 dest
+doc2path
+docname
 docutils
 formatter
+Formatter
 fromlist
-func
 lineno
 linesep
 metavar
@@ -18,9 +20,10 @@ parsers
 pathlib
 prog
 refid
+reftitle
 rst
 statemachine
 subparsers
+subtype
 testroot
 util
-addinivalue