revise --help output (and doc)

apply sonarcloud suggestions

Author: 2bndy5

clang_tools/main.py

@@ -20,7 +20,9 @@ def get_parser() -> argparse.ArgumentParser:
         "-i",
         "--install",
         metavar="VERSION",
-        help="Install clang-tools about a specific version.",
+        help="Install clang-tools about a specific version. This can be in the form of"
+        " a semantic version specification (``x.y.z``, ``x.y``, ``x``) or a path that "
+        "points to the directory where the binaries already exist.",
     )
     parser.add_argument(
         "-t",

docs/_static/extra_css.css

@@ -3,3 +3,46 @@ thead {
   background-color: var(--md-accent-bg-color--light);
   color: var(--md-default-bg-color);
 }
+
+.md-typeset .mdx-badge {
+  font-size: .85em
+}
+
+.md-typeset .mdx-badge--right {
+  float: right;
+  margin-left: .35em
+}
+
+[dir=ltr] .md-typeset .mdx-badge__icon {
+  border-top-left-radius: .1rem;
+  border-bottom-left-radius: .1rem;
+}
+
+[dir=rtl] .md-typeset .mdx-badge__icon {
+  border-top-right-radius: .1rem;
+  border-bottom-right-radius: .1rem;
+}
+
+.md-typeset .mdx-badge__icon {
+  background: var(--md-accent-fg-color--transparent);
+  padding: .2rem;
+}
+
+.md-typeset .mdx-badge__icon:last-child {
+  border-radius: .1rem;
+}
+
+[dir=ltr] .md-typeset .mdx-badge__text {
+  border-top-right-radius: .1rem;
+  border-bottom-right-radius: .1rem;
+}
+
+[dir=rtl] .md-typeset .mdx-badge__text {
+  border-top-left-radius: .1rem;
+  border-bottom-left-radius: .1rem;
+}
+
+.md-typeset .mdx-badge__text {
+  box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
+  padding: .2rem .3rem;
+}

docs/conf.py

@@ -4,8 +4,14 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from argparse import _StoreTrueAction
+from io import StringIO
 from pathlib import Path
+from typing import Optional
+import docutils
 from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxRole
+from sphinx_immaterial.inline_icons import load_svg_into_builder_env
 from clang_tools.main import get_parser
 
 # -- Path setup --------------------------------------------------------------
@@ -111,19 +117,126 @@
 # pylint: disable=protected-access
 
 
+class CliBadge(SphinxRole):
+    badge_type: str
+    badge_icon: Optional[str] = None
+    href: Optional[str] = None
+    href_title: Optional[str] = None
+
+    def run(self):
+        is_linked = ""
+        if self.href is not None and self.href_title is not None:
+            is_linked = (
+                f'<a href="{self.href}{self.text}" ' + f'title="{self.href_title}">'
+            )
+        head = '<span class="mdx-badge__icon">'
+        if not self.badge_icon:
+            head += self.badge_type.title()
+        else:
+            head += is_linked
+            head += (
+                f'<span class="md-icon si-icon-inline {self.badge_icon}"></span></a>'
+            )
+        head += "</span>"
+        header = docutils.nodes.raw(
+            self.rawtext,
+            f'<span class="mdx-badge">{head}<span class="mdx-badge__text">'
+            + is_linked
+            + (self.text if self.badge_type in ["version", "switch"] else ""),
+            format="html",
+        )
+        if self.badge_type not in ["version", "switch"]:
+            code, sys_msgs = docutils.parsers.rst.roles.code_role(
+                role="code",
+                rawtext=self.rawtext,
+                text=self.text,
+                lineno=self.lineno,
+                inliner=self.inliner,
+                options={"language": "text", "classes": ["highlight"]},
+                content=self.content,
+            )
+        else:
+            code, sys_msgs = ([], [])
+        tail = "</span></span>"
+        if self.href is not None and self.href_title is not None:
+            tail = "</a>" + tail
+        trailer = docutils.nodes.raw(self.rawtext, tail, format="html")
+        return ([header, *code, trailer], sys_msgs)
+
+
+class CliBadgeVersion(CliBadge):
+    badge_type = "version"
+    href = "https://github.com/cpp-linter/clang-tools-pip/releases/v"
+    href_title = "Minimum Version"
+
+    def run(self):
+        self.badge_icon = load_svg_into_builder_env(
+            self.env.app.builder, "material/tag-outline"
+        )
+        return super().run()
+
+
+class CliBadgeDefault(CliBadge):
+    badge_type = "Default"
+
+
+class CliBadgeSwitch(CliBadge):
+    badge_type = "switch"
+
+    def run(self):
+        self.badge_icon = load_svg_into_builder_env(
+            self.env.app.builder, "material/toggle-switch"
+        )
+        return super().run()
+
+
+REQUIRED_VERSIONS = {
+    "0.1.0": ["install"],
+    "0.2.0": ["directory"],
+    "0.3.0": ["overwrite"],
+    "0.5.0": ["no_progress_bar", "uninstall"],
+    "0.11.0": ["tool"],
+}
+
+
 def setup(app: Sphinx):
     """Generate a doc from the executable script's ``--help`` output."""
-    parser = get_parser()
-    # print(parser.format_help())
-    formatter = parser._get_formatter()
-    doc = "Command Line Interface Options\n==============================\n\n"
-    for arg in parser._actions:
-        doc += f"\n.. option:: {formatter._format_action_invocation(arg)}\n\n"
-        if arg.default != "==SUPPRESS==":
-            doc += f"    :Default: ``{repr(arg.default)}``\n\n"
-        description = (
-            "" if arg.help is None else "    %s\n" % (arg.help.replace("\n", "\n    "))
-        )
-        doc += description
+    app.add_role("badge-version", CliBadgeVersion())
+    app.add_role("badge-default", CliBadgeDefault())
+    app.add_role("badge-switch", CliBadgeSwitch())
+
     cli_doc = Path(app.srcdir, "cli_args.rst")
-    cli_doc.write_text(doc, encoding="utf-8")
+    with open(cli_doc, mode="w") as doc:
+        doc.write("Command Line Interface Options\n==============================\n\n")
+        parser = get_parser()
+        doc.write(".. code-block:: text\n    :caption: Usage\n    :class: no-copy\n\n")
+        parser.prog = "clang-tools"
+        str_buf = StringIO()
+        parser.print_usage(str_buf)
+        usage = str_buf.getvalue()
+        start = usage.find(parser.prog)
+        for line in usage.splitlines():
+            doc.write(f"    {line[start:]}\n")
+
+        args = parser._optionals._actions
+        for arg in args:
+            aliases = arg.option_strings
+            if not aliases or arg.default == "==SUPPRESS==":
+                continue
+            assert arg.help is not None
+            doc.write("\n.. std:option:: " + ", ".join(aliases) + "\n")
+            req_ver = "0.1.0"
+            for ver, names in REQUIRED_VERSIONS.items():
+                if arg.dest in names:
+                    req_ver = ver
+                    break
+            doc.write(f"\n    :badge-version:`{req_ver}` ")
+            if arg.default:
+                default = arg.default
+                if isinstance(arg.default, list):
+                    default = " ".join(arg.default)
+                doc.write(f":badge-default:`{default}` ")
+            if isinstance(arg, _StoreTrueAction):
+                doc.write(":badge-switch:`Accepts no value` ")
+            doc.write("\n\n    ")
+            doc.write("\n    ".join(arg.help.splitlines()) + "\n")