From 706f123b23b75097da9a3f51ce538bd784fdc75b Mon Sep 17 00:00:00 2001 From: Harry Mellor <19981378+hmellor@users.noreply.github.com> Date: Wed, 28 Jan 2026 02:22:48 +0000 Subject: [PATCH] [Docs] Use definition lists for CLI reference docs (#33186) Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com> Co-authored-by: Ashwin Phadke <23502062+ashwin-phadke@users.noreply.github.com> --- docs/mkdocs/hooks/generate_argparse.py | 16 ++++++++-------- mkdocs.yaml | 1 + 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/mkdocs/hooks/generate_argparse.py b/docs/mkdocs/hooks/generate_argparse.py index ecb18b1522..801cc8a05d 100644 --- a/docs/mkdocs/hooks/generate_argparse.py +++ b/docs/mkdocs/hooks/generate_argparse.py @@ -4,6 +4,7 @@ import importlib.metadata import importlib.util import logging import sys +import textwrap import traceback from argparse import SUPPRESS, Action, HelpFormatter from collections.abc import Iterable @@ -152,22 +153,21 @@ class MarkdownFormatter(HelpFormatter): heading_md = f"{self._argument_heading_prefix} {option_strings}\n\n" self._markdown_output.append(heading_md) - if choices := action.choices: - choices = f"`{'`, `'.join(str(c) for c in choices)}`" - self._markdown_output.append(f"Possible choices: {choices}\n\n") - elif (metavar := action.metavar) and isinstance(metavar, (list, tuple)): - metavar = f"`{'`, `'.join(str(m) for m in metavar)}`" - self._markdown_output.append(f"Possible choices: {metavar}\n\n") + if action.choices or isinstance(action.metavar, (list, tuple)): + choices_iterable = action.choices or action.metavar + choices = f"`{'`, `'.join(str(c) for c in choices_iterable)}`" + self._markdown_output.append(f": Possible choices: {choices}\n\n") if action.help: - self._markdown_output.append(f"{action.help}\n\n") + help_dd = ":" + textwrap.indent(action.help, " ")[1:] + self._markdown_output.append(f"{help_dd}\n\n") # None usually means the default is determined at runtime if (default := action.default) != SUPPRESS and default is not None: # Make empty string defaults visible if default == "": default = '""' - self._markdown_output.append(f"Default: `{default}`\n\n") + self._markdown_output.append(f": Default: `{default}`\n\n") def format_help(self): """Return the formatted help as markdown.""" diff --git a/mkdocs.yaml b/mkdocs.yaml index c5501e7db0..2797f6dee0 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -108,6 +108,7 @@ plugins: markdown_extensions: - attr_list + - def_list - md_in_html - admonition - pymdownx.details