mirror of
https://github.com/torvalds/linux.git
synced 2025-11-30 23:16:01 +07:00
cde494660f
As suggested by Jon, we should start having a tools/docs directory, instead of placing everything under scripts. In the specific case of parse-headers.py, the previous location is where we're placing Sphinx extensions, which is not the right place for execs. Move it to tools/docs/parse-headers.py. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org
71 lines
2.5 KiB
Python
71 lines
2.5 KiB
Python
#!/usr/bin/env python3
|
|
# SPDX-License-Identifier: GPL-2.0
|
|
# Copyright (c) 2025 by Mauro Carvalho Chehab <mchehab@kernel.org>.
|
|
|
|
"""
|
|
Ancillary argparse HelpFormatter class that works on a similar way as
|
|
argparse.RawDescriptionHelpFormatter, e.g. description maintains line
|
|
breaks, but it also implement transformations to the help text. The
|
|
actual transformations ar given by enrich_text(), if the output is tty.
|
|
|
|
Currently, the follow transformations are done:
|
|
|
|
- Positional arguments are shown in upper cases;
|
|
- if output is TTY, ``var`` and positional arguments are shown prepended
|
|
by an ANSI SGR code. This is usually translated to bold. On some
|
|
terminals, like, konsole, this is translated into a colored bold text.
|
|
"""
|
|
|
|
import argparse
|
|
import re
|
|
import sys
|
|
|
|
class EnrichFormatter(argparse.HelpFormatter):
|
|
"""
|
|
Better format the output, making easier to identify the positional args
|
|
and how they're used at the __doc__ description.
|
|
"""
|
|
def __init__(self, *args, **kwargs):
|
|
"""Initialize class and check if is TTY"""
|
|
super().__init__(*args, **kwargs)
|
|
self._tty = sys.stdout.isatty()
|
|
|
|
def enrich_text(self, text):
|
|
"""Handle ReST markups (currently, only ``foo``)"""
|
|
if self._tty and text:
|
|
# Replace ``text`` with ANSI SGR (bold)
|
|
return re.sub(r'\`\`(.+?)\`\`',
|
|
lambda m: f'\033[1m{m.group(1)}\033[0m', text)
|
|
return text
|
|
|
|
def _fill_text(self, text, width, indent):
|
|
"""Enrich descriptions with markups on it"""
|
|
enriched = self.enrich_text(text)
|
|
return "\n".join(indent + line for line in enriched.splitlines())
|
|
|
|
def _format_usage(self, usage, actions, groups, prefix):
|
|
"""Enrich positional arguments at usage: line"""
|
|
|
|
prog = self._prog
|
|
parts = []
|
|
|
|
for action in actions:
|
|
if action.option_strings:
|
|
opt = action.option_strings[0]
|
|
if action.nargs != 0:
|
|
opt += f" {action.dest.upper()}"
|
|
parts.append(f"[{opt}]")
|
|
else:
|
|
# Positional argument
|
|
parts.append(self.enrich_text(f"``{action.dest.upper()}``"))
|
|
|
|
usage_text = f"{prefix or 'usage: '} {prog} {' '.join(parts)}\n"
|
|
return usage_text
|
|
|
|
def _format_action_invocation(self, action):
|
|
"""Enrich argument names"""
|
|
if not action.option_strings:
|
|
return self.enrich_text(f"``{action.dest.upper()}``")
|
|
|
|
return ", ".join(action.option_strings)
|