revise --help output (and doc)

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,58 @@ 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
+}
+
+[dir=rtl] .md-typeset .mdx-badge__icon {
+ border-top-right-radius: .1rem
+}
+
+[dir=ltr] .md-typeset .mdx-badge__icon {
+ border-bottom-left-radius: .1rem
+}
+
+[dir=rtl] .md-typeset .mdx-badge__icon {
+ 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
+}
+
+[dir=rtl] .md-typeset .mdx-badge__text {
+ border-top-left-radius: .1rem
+}
+
+[dir=ltr] .md-typeset .mdx-badge__text {
+ border-bottom-right-radius: .1rem
+}
+
+[dir=rtl] .md-typeset .mdx-badge__text {
+ 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,128 @@
 # 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
+ doc.write("\n.. std:option:: " + ", ".join(aliases) + "\n")
+ assert arg.help is not None
+ help = arg.help[: arg.help.find("Defaults to")]
+ for ver, names in REQUIRED_VERSIONS.items():
+ if arg.dest in names:
+ req_ver = ver
+ break
+ else:
+ req_ver = "0.1.0"
+ 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(help.splitlines()) + "\n")