Classes
class	BulletBlocks
class	ScannedBlocks

Functions
ScannedBlocks	_scan_bullet_blocks (Sequence[str] lines, int start, int end)
str	read_text (str path)
None	write_text (str path, str content)
bool	_is_markdown_table_header (Sequence[str] lines, int index)
List[str]	_normalize_list_md_lines (Sequence[str] lines)
str	normalize_list_md (str data)
Optional[int]	find_heading (Sequence[str] lines, str title)
str	extract_label (str text)
bool	_is_bullet_start (str line)
BulletBlocks	_parse_bullet_blocks (Sequence[str] lines, int start, int end)
List[BulletBlock]	sort_blocks (Iterable[BulletItem] blocks)
List[Tuple[CheckLabel, DuplicateOccurrences]]	find_duplicate_entries (Sequence[str] lines, str title)
Optional[Tuple[int, int, int]]	_find_section_bounds (Sequence[str] lines, str title, Optional[str] next_title)
List[str]	_normalize_release_notes_section (Sequence[str] lines, str title, Optional[str] next_title)
str	normalize_release_notes (Sequence[str] lines)
Optional[str]	_emit_duplicate_report (Sequence[str] lines, str title)
int	process_release_notes (str out_path, str rn_doc)
int	process_checks_list (str out_path, str list_doc)
int	main (Sequence[str] argv)

Variables
Final	DOC_LABEL_RN_RE = re.compile(r"\{doc\}`(?P<label>[^`<]+)\s*(?:<[^>]+>)?`")
Final	DOC_LINE_RE = re.compile(r"^\\|\s\{doc\}`(?P<label>[^`<]+?)\s<[^>]+>`.*$")
Final	EXTRA_DIR = os.path.join(os.path.dirname(__file__), "../..")
Final	DOCS_DIR = os.path.join(EXTRA_DIR, "docs")
Final	CLANG_TIDY_DOCS_DIR = os.path.join(DOCS_DIR, "clang-tidy")
Final	CHECKS_DOCS_DIR = os.path.join(CLANG_TIDY_DOCS_DIR, "checks")
Final	LIST_DOC = os.path.join(CHECKS_DOCS_DIR, "list.md")
Final	RELEASE_NOTES_DOC = os.path.join(DOCS_DIR, "ReleaseNotes.md")
	CheckLabel = str
	Lines = List[str]
	BulletBlock = List[str]
	BulletItem = Tuple[CheckLabel, BulletBlock]
	BulletStart = int
	DuplicateOccurrences = List[Tuple[BulletStart, BulletBlock]]

Detailed Description

Clang-Tidy Alphabetical Order Checker
=====================================

Normalize Clang-Tidy documentation with deterministic sorting for linting/tests.

Behavior:
- Sort entries in docs/clang-tidy/checks/list.md Markdown tables.
- Sort key sections in docs/ReleaseNotes.md.
- Detect duplicated entries in 'Changes in existing checks'.

Flags:
  -o/--output  Write normalized content to this path instead of updating docs.

Function Documentation

◆ _emit_duplicate_report()

Optional[str] check_alphabetical_order._emit_duplicate_report	(	Sequence[str]	lines,
		str	title )

protected

Definition at line 344 of file check_alphabetical_order.py.

References find_duplicate_entries().

Referenced by process_release_notes().

◆ _find_section_bounds()

Optional[Tuple[int, int, int]] check_alphabetical_order._find_section_bounds	(	Sequence[str]	lines,
		str	title,
		Optional[str]	next_title )

protected

Return (h_start, sec_start, sec_end) for section `title`.

- h_start: index of the section title line
- sec_start: index of the first content line after the heading
- sec_end: index of the first line of the next section title (or end)

Definition at line 271 of file check_alphabetical_order.py.

References find_heading().

Referenced by _normalize_release_notes_section(), and find_duplicate_entries().

◆ _is_bullet_start()

bool check_alphabetical_order._is_bullet_start ( str line )

protected

Definition at line 202 of file check_alphabetical_order.py.

Referenced by _parse_bullet_blocks(), _scan_bullet_blocks(), and find_duplicate_entries().

◆ _is_markdown_table_header()

bool check_alphabetical_order._is_markdown_table_header	(	Sequence[str]	lines,
		int	index )

protected

Definition at line 135 of file check_alphabetical_order.py.

Referenced by _normalize_list_md_lines().

◆ _normalize_list_md_lines()

List[str] check_alphabetical_order._normalize_list_md_lines ( Sequence[str] lines )

protected

Return normalized content of checks list.md as a list of lines.

Definition at line 143 of file check_alphabetical_order.py.

References _is_markdown_table_header().

Referenced by normalize_list_md().

◆ _normalize_release_notes_section()

List[str] check_alphabetical_order._normalize_release_notes_section	(	Sequence[str]	lines,
		str	title,
		Optional[str]	next_title )

protected

Normalize a single release-notes section and return updated lines.

Definition at line 307 of file check_alphabetical_order.py.

References _find_section_bounds(), _parse_bullet_blocks(), and sort_blocks().

Referenced by normalize_release_notes().

◆ _parse_bullet_blocks()

BulletBlocks check_alphabetical_order._parse_bullet_blocks	(	Sequence[str]	lines,
		int	start,
		int	end )

protected

Definition at line 206 of file check_alphabetical_order.py.

References _is_bullet_start(), _scan_bullet_blocks(), and extract_label().

Referenced by _normalize_release_notes_section().

◆ _scan_bullet_blocks()

ScannedBlocks check_alphabetical_order._scan_bullet_blocks	(	Sequence[str]	lines,
		int	start,
		int	end )

protected

Scan consecutive bullet blocks and return (blocks_with_pos, next_index).

Each entry in blocks_with_pos is a tuple of (start_index, block_lines).
next_index is the index where scanning stopped (start of suffix).

Definition at line 102 of file check_alphabetical_order.py.

References _is_bullet_start().

Referenced by _parse_bullet_blocks(), and find_duplicate_entries().

◆ extract_label()

str check_alphabetical_order.extract_label ( str text )

Definition at line 196 of file check_alphabetical_order.py.

Referenced by _parse_bullet_blocks(), and find_duplicate_entries().

◆ find_duplicate_entries()

List[Tuple[CheckLabel, DuplicateOccurrences]] check_alphabetical_order.find_duplicate_entries	(	Sequence[str]	lines,
		str	title )

Return detailed duplicate info as (key, [(start_idx, block_lines), ...]).

start_idx is the 0-based index of the first line of the bullet block in
the original lines list. Only keys with more than one occurrence are
returned, and occurrences are listed in the order they appear.

Definition at line 232 of file check_alphabetical_order.py.

References _find_section_bounds(), _is_bullet_start(), _scan_bullet_blocks(), and extract_label().

Referenced by _emit_duplicate_report().

◆ find_heading()

Optional[int] check_alphabetical_order.find_heading	(	Sequence[str]	lines,
		str	title )

Find heading start index for a Markdown #### section heading.

The function looks for a line equal to `#### {title}`, matching the
ReleaseNotes.md style for subsection headings.

Returns index of the title line, or None if not found.

Definition at line 181 of file check_alphabetical_order.py.

Referenced by _find_section_bounds().

◆ main()

int check_alphabetical_order.main ( Sequence[str] argv )

Definition at line 395 of file check_alphabetical_order.py.

References main(), process_checks_list(), and process_release_notes().

Referenced by main().

◆ normalize_list_md()

str check_alphabetical_order.normalize_list_md ( str data )

Normalize list.md content and return a string.

Definition at line 175 of file check_alphabetical_order.py.

References _normalize_list_md_lines().

Referenced by process_checks_list().

◆ normalize_release_notes()

str check_alphabetical_order.normalize_release_notes ( Sequence[str] lines )

Definition at line 331 of file check_alphabetical_order.py.

References _normalize_release_notes_section().

Referenced by process_release_notes().

◆ process_checks_list()

int check_alphabetical_order.process_checks_list	(	str	out_path,
		str	list_doc )

Definition at line 381 of file check_alphabetical_order.py.

References normalize_list_md(), read_text(), and write_text().

Referenced by main().

◆ process_release_notes()

int check_alphabetical_order.process_release_notes	(	str	out_path,
		str	rn_doc )

Definition at line 360 of file check_alphabetical_order.py.

References _emit_duplicate_report(), normalize_release_notes(), read_text(), and write_text().

Referenced by main().

◆ read_text()

str check_alphabetical_order.read_text ( str path )

Definition at line 125 of file check_alphabetical_order.py.

Referenced by process_checks_list(), and process_release_notes().

◆ sort_blocks()

List[BulletBlock] check_alphabetical_order.sort_blocks ( Iterable[BulletItem] blocks )

Return blocks sorted deterministically by their extracted label.

Duplicates are preserved; merging is left to authors to handle manually.

Definition at line 224 of file check_alphabetical_order.py.

Referenced by _normalize_release_notes_section().

◆ write_text()

None check_alphabetical_order.write_text	(	str	path,
		str	content )

Definition at line 130 of file check_alphabetical_order.py.

Referenced by process_checks_list(), and process_release_notes().

Variable Documentation

◆ BulletBlock

check_alphabetical_order.BulletBlock = List[str]

Definition at line 66 of file check_alphabetical_order.py.

◆ BulletItem

check_alphabetical_order.BulletItem = Tuple[CheckLabel, BulletBlock]

Definition at line 69 of file check_alphabetical_order.py.

◆ BulletStart

check_alphabetical_order.BulletStart = int

Definition at line 72 of file check_alphabetical_order.py.

◆ CheckLabel

check_alphabetical_order.CheckLabel = str

Definition at line 64 of file check_alphabetical_order.py.

◆ CHECKS_DOCS_DIR

Final check_alphabetical_order.CHECKS_DOCS_DIR = os.path.join(CLANG_TIDY_DOCS_DIR, "checks")

Definition at line 58 of file check_alphabetical_order.py.

◆ CLANG_TIDY_DOCS_DIR

Final check_alphabetical_order.CLANG_TIDY_DOCS_DIR = os.path.join(DOCS_DIR, "clang-tidy")

Definition at line 57 of file check_alphabetical_order.py.

◆ DOC_LABEL_RN_RE

Final check_alphabetical_order.DOC_LABEL_RN_RE = re.compile(r"\{doc\}`(?P<label>[^`<]+)\s*(?:<[^>]+>)?`")

Definition at line 48 of file check_alphabetical_order.py.

◆ DOC_LINE_RE

Final check_alphabetical_order.DOC_LINE_RE = re.compile(r"^\|\s*\{doc\}`(?P<label>[^`<]+?)\s*<[^>]+>`.*$")

Definition at line 52 of file check_alphabetical_order.py.

◆ DOCS_DIR

Final check_alphabetical_order.DOCS_DIR = os.path.join(EXTRA_DIR, "docs")

Definition at line 56 of file check_alphabetical_order.py.

◆ DuplicateOccurrences

check_alphabetical_order.DuplicateOccurrences = List[Tuple[BulletStart, BulletBlock]]

Definition at line 75 of file check_alphabetical_order.py.

◆ EXTRA_DIR

Final check_alphabetical_order.EXTRA_DIR = os.path.join(os.path.dirname(__file__), "../..")

Definition at line 55 of file check_alphabetical_order.py.

◆ Lines

check_alphabetical_order.Lines = List[str]

Definition at line 65 of file check_alphabetical_order.py.

◆ LIST_DOC

Final check_alphabetical_order.LIST_DOC = os.path.join(CHECKS_DOCS_DIR, "list.md")

Definition at line 59 of file check_alphabetical_order.py.

◆ RELEASE_NOTES_DOC

Final check_alphabetical_order.RELEASE_NOTES_DOC = os.path.join(DOCS_DIR, "ReleaseNotes.md")

Definition at line 60 of file check_alphabetical_order.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _emit_duplicate_report()

◆ _find_section_bounds()

◆ _is_bullet_start()

◆ _is_markdown_table_header()

◆ _normalize_list_md_lines()

◆ _normalize_release_notes_section()

◆ _parse_bullet_blocks()

◆ _scan_bullet_blocks()

◆ extract_label()

◆ find_duplicate_entries()

◆ find_heading()

◆ main()

◆ normalize_list_md()

◆ normalize_release_notes()

◆ process_checks_list()

◆ process_release_notes()

◆ read_text()

◆ sort_blocks()

◆ write_text()

Variable Documentation

◆ BulletBlock

◆ BulletItem

◆ BulletStart

◆ CheckLabel

◆ CHECKS_DOCS_DIR

◆ CLANG_TIDY_DOCS_DIR

◆ DOC_LABEL_RN_RE

◆ DOC_LINE_RE

◆ DOCS_DIR

◆ DuplicateOccurrences

◆ EXTRA_DIR

◆ Lines

◆ LIST_DOC

◆ RELEASE_NOTES_DOC