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)
List[str]	_normalize_list_rst_lines (Sequence[str] lines)
str	normalize_list_rst (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.rst")
Final	RELEASE_NOTES_DOC = os.path.join(DOCS_DIR, "ReleaseNotes.rst")
	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.rst csv-table.
- Sort key sections in docs/ReleaseNotes.rst.
- 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 351 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 underline
- sec_end: index of the first line of the next section title (or end)

Definition at line 278 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 209 of file check_alphabetical_order.py.

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

◆ _normalize_list_rst_lines()

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

protected

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

Definition at line 139 of file check_alphabetical_order.py.

Referenced by normalize_list_rst().

◆ _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 314 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 213 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 203 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 239 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 section underlined with ^ characters.

The function looks for a line equal to `title` followed by a line that
consists solely of ^, which matches the ReleaseNotes style for subsection
headings used here.

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

Definition at line 183 of file check_alphabetical_order.py.

Referenced by _find_section_bounds().

◆ main()

int check_alphabetical_order.main ( Sequence[str] argv )

Definition at line 401 of file check_alphabetical_order.py.

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

Referenced by main().

◆ normalize_list_rst()

str check_alphabetical_order.normalize_list_rst ( str data )

Normalize list.rst content and return a string.

Definition at line 177 of file check_alphabetical_order.py.

References _normalize_list_rst_lines().

Referenced by process_checks_list().

◆ normalize_release_notes()

str check_alphabetical_order.normalize_release_notes ( Sequence[str] lines )

Definition at line 338 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 387 of file check_alphabetical_order.py.

References normalize_list_rst(), 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 366 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 129 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 231 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 134 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.rst")

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.rst")

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()

◆ _normalize_list_rst_lines()

◆ _normalize_release_notes_section()

◆ _parse_bullet_blocks()

◆ _scan_bullet_blocks()

◆ extract_label()

◆ find_duplicate_entries()

◆ find_heading()

◆ main()

◆ normalize_list_rst()

◆ 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