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