File: cpdocs/rendering/common.py
1# --------------------------------------------------------------------------------------------------2# SPDX-License-Identifier: Apache-2.03# SPDX-FileCopyrightText: 2026 cpdocs developers4# --------------------------------------------------------------------------------------------------5"""Shared rendering helpers for cpdocs' code-oriented API layout."""6 7from __future__ import annotations8 9import collections.abc10import hashlib11import html12import pathlib13import re14 15try:16 import pygments17 import pygments.formatters18 import pygments.lexers19except ImportError: # pragma: no cover - optional dependency in some bootstrap environments20 highlight = None21 lex = None22 HtmlFormatter = None23 CppLexer = FortranLexer = PythonLexer = RustLexer = TextLexer = None24 25import cpdocs.languages26import cpdocs.model27 28 29def split_qualified(name: str, separator: str) -> list[str]:30 """Split a qualified name on ``separator`` outside template argument lists."""31 32 parts: list[str] = []33 depth = 034 start = 035 index = 036 while index < len(name):37 character = name[index]38 if character == "<":39 depth += 140 elif character == ">":41 depth = max(0, depth - 1)42 elif depth == 0 and name.startswith(separator, index):43 parts.append(name[start:index])44 index += len(separator)45 start = index46 continue47 index += 148 parts.append(name[start:])49 return [part for part in parts if part]50 51 52def _segments(entity: cpdocs.model.ApiEntity) -> list[str]:53 return split_qualified(entity.qualified_name, cpdocs.languages.rendering_for(entity.language).separator)54 55 56# Operator names as words, longest spelling first, so that ``operator<<`` is not read as ``<``.57_OPERATOR_WORDS = (58 ("<=>", "spaceship"),59 ("<<=", "shl-assign"),60 (">>=", "shr-assign"),61 ("->*", "arrow-star"),62 ("new[]", "new-array"),63 ("delete[]", "delete-array"),64 ('""', "literal"),65 ("()", "call"),66 ("[]", "subscript"),67 ("->", "arrow"),68 ("<<", "shl"),69 (">>", "shr"),70 ("==", "eq"),71 ("!=", "ne"),72 ("<=", "le"),73 (">=", "ge"),74 ("&&", "and"),75 ("||", "or"),76 ("++", "inc"),77 ("--", "dec"),78 ("+=", "add-assign"),79 ("-=", "sub-assign"),80 ("*=", "mul-assign"),81 ("/=", "div-assign"),82 ("%=", "mod-assign"),83 ("&=", "and-assign"),84 ("|=", "or-assign"),85 ("^=", "xor-assign"),86 ("<", "lt"),87 (">", "gt"),88 ("+", "add"),89 ("-", "sub"),90 ("*", "mul"),91 ("/", "div"),92 ("%", "mod"),93 ("&", "bitand"),94 ("|", "bitor"),95 ("^", "xor"),96 ("~", "compl"),97 ("!", "not"),98 ("=", "assign"),99 (",", "comma"),100)101 102# Symbols inside template arguments that must stay distinguishable, spelled as words.103_TYPE_WORDS = (("...", " pack "), ("&&", " rref "), ("&", " ref "), ("*", " ptr "), ("[]", " array "))104 105 106def _slug(value: str) -> str:107 """A readable URL segment for one name component.108 109 ``storage_traits<bool>`` becomes ``storage_traits-bool``, ``vec<T, 0>`` becomes ``vec-t-0``110 and ``operator[]`` becomes ``operator-subscript``. Names that still collide after this are told111 apart when a site is rendered, see :func:`assign_documents`.112 """113 114 text = value.strip()115 operator = re.fullmatch(r"operator\s*(.+)", text)116 if operator is not None:117 tail = operator.group(1).replace(" ", "")118 for spelling, word in _OPERATOR_WORDS:119 if tail == spelling:120 return f"operator-{word}"121 for spelling, word in _TYPE_WORDS:122 text = text.replace(spelling, word)123 cleaned = re.sub(r"[^A-Za-z0-9_]+", "-", text).strip("-").lower()124 return cleaned or "symbol"125 126 127# Documents of entities whose readable path collides with another entity's, set per rendered site.128_DOCUMENT_OVERRIDES: dict[str, pathlib.Path] = {}129 130 131def assign_documents(entities: collections.abc.Iterable[cpdocs.model.ApiEntity]) -> None:132 """Resolve path collisions between entities before a site is rendered.133 134 Entities whose readable document path is shared get a short digest of their qualified name135 appended; all other paths stay readable and do not depend on the rest of the API.136 """137 138 _DOCUMENT_OVERRIDES.clear()139 by_path: dict[pathlib.Path, list[cpdocs.model.ApiEntity]] = {}140 for entity in entities:141 by_path.setdefault(entity_document(entity), []).append(entity)142 for path, values in by_path.items():143 if len(values) < 2:144 continue145 for entity in values:146 key = f"{entity.language}:{entity.kind}:{entity.qualified_name}"147 digest = hashlib.sha1(key.encode("utf-8")).hexdigest()[:7]148 if path.name == "index.md":149 _DOCUMENT_OVERRIDES[entity.id] = path.parent.with_name(f"{path.parent.name}-{digest}") / "index.md"150 else:151 _DOCUMENT_OVERRIDES[entity.id] = path.with_name(f"{path.stem}-{digest}.md")152 153 154def entity_document(entity: cpdocs.model.ApiEntity) -> pathlib.Path:155 override = _DOCUMENT_OVERRIDES.get(entity.id)156 if override is not None:157 return override158 rendering = cpdocs.languages.rendering_for(entity.language)159 parts = [_slug(part) for part in _segments(entity)]160 if entity.kind in rendering.container_kinds:161 return pathlib.Path("api", *parts, "index.md")162 if entity.kind in rendering.type_page_kinds:163 if len(parts) > 1:164 return pathlib.Path("api", *parts[:-1], f"{entity.kind}-{parts[-1]}", "index.md")165 return pathlib.Path("api", f"{entity.kind}-{parts[0]}", "index.md")166 if len(parts) > 1:167 return pathlib.Path("api", *parts[:-1], f"{entity.kind}-{parts[-1]}.md")168 return pathlib.Path("api", f"{entity.kind}-{parts[0]}.md")169 170 171def _source_document(source_path: str) -> pathlib.Path:172 logical = pathlib.Path(source_path)173 return pathlib.Path("_sources", *logical.parent.parts, logical.name + ".md")174 175 176def _source_language(source_path: str) -> str:177 return cpdocs.languages.source_language(source_path)178 179 180def _pygments_lexer(language: str):181 lexer_map = {182 "c": pygments.lexers.CppLexer,183 "cpp": pygments.lexers.CppLexer,184 "cuda": pygments.lexers.CppLexer,185 "hip": pygments.lexers.CppLexer,186 "fortran": pygments.lexers.FortranLexer,187 "python": pygments.lexers.PythonLexer,188 "rust": pygments.lexers.RustLexer,189 }190 lexer_type = lexer_map.get(language, pygments.lexers.TextLexer)191 return lexer_type() if lexer_type is not None else None192 193 194_FALLBACK_KEYWORDS = {195 "cpp": {196 "alignas",197 "alignof",198 "asm",199 "auto",200 "bool",201 "break",202 "case",203 "catch",204 "char",205 "char8_t",206 "char16_t",207 "char32_t",208 "class",209 "concept",210 "const",211 "consteval",212 "constexpr",213 "constinit",214 "const_cast",215 "continue",216 "co_await",217 "co_return",218 "co_yield",219 "decltype",220 "default",221 "delete",222 "do",223 "double",224 "dynamic_cast",225 "else",226 "enum",227 "explicit",228 "export",229 "extern",230 "false",231 "float",232 "for",233 "friend",234 "goto",235 "if",236 "inline",237 "int",238 "long",239 "mutable",240 "namespace",241 "new",242 "noexcept",243 "nullptr",244 "operator",245 "private",246 "protected",247 "public",248 "register",249 "reinterpret_cast",250 "requires",251 "return",252 "short",253 "signed",254 "sizeof",255 "static",256 "static_assert",257 "static_cast",258 "struct",259 "switch",260 "template",261 "this",262 "thread_local",263 "throw",264 "true",265 "try",266 "typedef",267 "typeid",268 "typename",269 "union",270 "unsigned",271 "using",272 "virtual",273 "void",274 "volatile",275 "wchar_t",276 "while",277 },278 "python": {279 "and",280 "as",281 "assert",282 "async",283 "await",284 "break",285 "class",286 "continue",287 "def",288 "del",289 "elif",290 "else",291 "except",292 "False",293 "finally",294 "for",295 "from",296 "global",297 "if",298 "import",299 "in",300 "is",301 "lambda",302 "None",303 "nonlocal",304 "not",305 "or",306 "pass",307 "raise",308 "return",309 "True",310 "try",311 "while",312 "with",313 "yield",314 },315 "rust": {316 "as",317 "async",318 "await",319 "break",320 "const",321 "continue",322 "crate",323 "dyn",324 "else",325 "enum",326 "extern",327 "false",328 "fn",329 "for",330 "if",331 "impl",332 "in",333 "let",334 "loop",335 "match",336 "mod",337 "move",338 "mut",339 "pub",340 "ref",341 "return",342 "self",343 "Self",344 "static",345 "struct",346 "super",347 "trait",348 "true",349 "type",350 "unsafe",351 "use",352 "where",353 "while",354 },355}356 357 358_FALLBACK_TOKEN = re.compile(359 r"//[^\n]*|/\*.*?\*/|#[^\n]*|\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*'|"360 r"\b(?:0[xX][0-9A-Fa-f]+|\d+(?:\.\d+)?)\b|\b[A-Za-z_]\w*\b|\s+|.",361 re.DOTALL,362)363 364 365def _fallback_lex(code: str, language: str) -> list[tuple[str, str]]:366 """Small built-in highlighter used when Pygments is unavailable at render time."""367 368 normalized_language = "cpp" if language in {"c", "cuda", "hip"} else language369 keywords = _FALLBACK_KEYWORDS.get(normalized_language, set())370 values: list[tuple[str, str]] = []371 for match in _FALLBACK_TOKEN.finditer(code):372 token = match.group(0)373 if language in {"c", "cpp", "cuda", "hip"} and token.startswith("#"):374 kind = "preprocessor"375 elif token.startswith("//") or token.startswith("/*") or (language == "python" and token.startswith("#")):376 kind = "comment"377 elif token.startswith(('"', "'")):378 kind = "string"379 elif re.fullmatch(r"(?:0[xX][0-9A-Fa-f]+|\d+(?:\.\d+)?)", token):380 kind = "number"381 elif re.fullmatch(r"[A-Za-z_]\w*", token):382 kind = "keyword" if token in keywords else "name"383 else:384 kind = "plain"385 values.append((kind, token))386 return values387 388 389def _fallback_token_html(kind: str, value: str) -> str:390 escaped = html.escape(value)391 if kind == "plain" or not value.strip():392 return escaped393 return f'<span class="cpdocs-syntax-{kind}">{escaped}</span>'394 395 396def _token_style(formatter: pygments.formatters.HtmlFormatter, token_type) -> str:397 style = formatter.style.style_for_token(token_type)398 values: list[str] = []399 if style.get("color"):400 values.append(f"color: #{style['color']}")401 if style.get("bgcolor"):402 values.append(f"background-color: #{style['bgcolor']}")403 if style.get("bold"):404 values.append("font-weight: bold")405 if style.get("italic"):406 values.append("font-style: italic")407 if style.get("underline"):408 values.append("text-decoration: underline")409 return "; ".join(values)410 411 412def _highlight_source_lines(content: str, language: str) -> list[str]:413 if pygments.lex is None or pygments.formatters.HtmlFormatter is None:414 rendered: list[list[str]] = [[]]415 for kind, value in _fallback_lex(content, language):416 parts = value.split("\n")417 for index, part in enumerate(parts):418 if part:419 rendered[-1].append(_fallback_token_html(kind, part))420 if index + 1 < len(parts):421 rendered.append([])422 if content.endswith("\n") and rendered and not rendered[-1]:423 rendered.pop()424 return ["".join(parts) or " " for parts in rendered]425 426 lexer = _pygments_lexer(language)427 if lexer is None:428 return [html.escape(value) or " " for value in content.splitlines()]429 430 formatter = pygments.formatters.HtmlFormatter(noclasses=True, style="friendly")431 rendered: list[list[str]] = [[]]432 for token_type, value in pygments.lex(content, lexer):433 style = _token_style(formatter, token_type)434 parts = value.split("\n")435 for index, part in enumerate(parts):436 if part:437 escaped = html.escape(part)438 if style:439 rendered[-1].append(f'<span style="{html.escape(style, quote=True)}">{escaped}</span>')440 else:441 rendered[-1].append(escaped)442 if index + 1 < len(parts):443 rendered.append([])444 445 # lex() normally preserves the final newline as an empty logical line. Do not add an extra446 # displayed line for that terminator; line numbers should match the source file exactly.447 if content.endswith("\n") and rendered and not rendered[-1]:448 rendered.pop()449 return ["".join(parts) or " " for parts in rendered]450 451 452def _is_container(entity: cpdocs.model.ApiEntity) -> bool:453 return entity.kind in cpdocs.languages.rendering_for(entity.language).container_kinds454 455 456def _is_class_like(entity: cpdocs.model.ApiEntity) -> bool:457 return entity.kind in cpdocs.languages.rendering_for(entity.language).class_like_kinds458 459 460def _is_type_page(entity: cpdocs.model.ApiEntity) -> bool:461 return entity.kind in cpdocs.languages.rendering_for(entity.language).type_page_kinds462 463 464def _is_function(entity: cpdocs.model.ApiEntity) -> bool:465 return entity.kind in cpdocs.languages.rendering_for(entity.language).function_kinds466 467 468def _preferred_type_target(469 name: str, entity: cpdocs.model.ApiEntity, graph: cpdocs.model.ApiGraph470) -> cpdocs.model.ApiEntity | None:471 candidates = [472 candidate473 for candidate in graph.entities.values()474 if candidate.kind in cpdocs.languages.rendering_for(candidate.language).type_like_kinds475 and candidate.name == name476 ]477 if not candidates:478 return None479 if entity.parent:480 same_parent = [candidate for candidate in candidates if candidate.parent == entity.parent]481 if len(same_parent) == 1:482 return same_parent[0]483 return candidates[0] if len(candidates) == 1 else None484 485 486def _embedded_member_parent(487 entity: cpdocs.model.ApiEntity, graph: cpdocs.model.ApiGraph488) -> cpdocs.model.ApiEntity | None:489 if not entity.parent or entity.parent not in graph.entities:490 return None491 parent = graph.entities[entity.parent]492 return parent if _is_class_like(parent) else None493 494 495def _member_anchor(entity: cpdocs.model.ApiEntity) -> str:496 return f"member-{_slug(entity.kind)}-{_slug(entity.name)}"497 498 499def _entity_href(document_path: pathlib.Path, entity: cpdocs.model.ApiEntity, graph: cpdocs.model.ApiGraph) -> str:500 parent = _embedded_member_parent(entity, graph)501 if parent is not None:502 return _relative_link(document_path, entity_document(parent)) + f"#{_member_anchor(entity)}"503 return _relative_link(document_path, entity_document(entity))504 505 506def _highlight_declaration(507 code: str,508 language: str,509 *,510 entity: cpdocs.model.ApiEntity,511 graph: cpdocs.model.ApiGraph,512 document_path: pathlib.Path,513) -> str:514 """Highlight a declaration and add semantic links to known API types."""515 516 if pygments.lex is None or pygments.formatters.HtmlFormatter is None:517 values: list[str] = []518 for kind, value in _fallback_lex(code, language):519 token_html = _fallback_token_html(kind, value)520 stripped = value.strip()521 if kind == "name" and stripped:522 target = _preferred_type_target(stripped, entity, graph)523 if target is not None and target.id != entity.id:524 href = _entity_href(document_path, target, graph)525 token_html = (526 f'<a class="cpdocs-api-signature-type" href="{html.escape(href)}">' + token_html + "</a>"527 )528 elif stripped == entity.name:529 token_html = f'<span class="cpdocs-api-signature-name">{token_html}</span>'530 values.append(token_html)531 return "".join(values)532 533 lexer = _pygments_lexer(language)534 if lexer is None:535 return html.escape(code)536 537 formatter = pygments.formatters.HtmlFormatter(noclasses=True, style="friendly")538 values: list[str] = []539 tokens = list(pygments.lex(code, lexer))540 if tokens and tokens[-1][1] == "\n":541 tokens.pop()542 for token_type, value in tokens:543 if not value:544 continue545 style = _token_style(formatter, token_type)546 escaped = html.escape(value)547 token_html = f'<span style="{html.escape(style, quote=True)}">{escaped}</span>' if style else escaped548 549 stripped = value.strip()550 if stripped and re.fullmatch(r"[A-Za-z_]\w*", stripped):551 target = _preferred_type_target(stripped, entity, graph)552 if target is not None and target.id != entity.id:553 href = _entity_href(document_path, target, graph)554 token_html = f'<a class="cpdocs-api-signature-type" href="{html.escape(href)}">' + token_html + "</a>"555 elif stripped == entity.name:556 token_html = f'<span class="cpdocs-api-signature-name">{token_html}</span>'557 values.append(token_html)558 return "".join(values)559 560 561def _signature_spelling(entity: cpdocs.model.ApiEntity, signature: cpdocs.model.ApiSignature) -> str:562 value = cpdocs.languages.rendering_for(entity.language).signature_spelling(entity, signature)563 return f"{signature.template}\n{value}" if signature.template else value564 565 566def _plain_signature_spelling(entity: cpdocs.model.ApiEntity, signature: cpdocs.model.ApiSignature) -> str:567 return cpdocs.languages.rendering_for(entity.language).signature_spelling(entity, signature)568 569 570def _entity_declaration(entity: cpdocs.model.ApiEntity) -> str:571 return cpdocs.languages.rendering_for(entity.language).entity_declaration(entity)572 573 574def _paragraphs(text: str) -> str:575 if not text.strip():576 return '<p class="cpdocs-api-undocumented">No API documentation has been provided.</p>'577 return "\n".join(578 f"<p>{html.escape(paragraph.strip())}</p>"579 for paragraph in re.split(r"\n\s*\n", text.strip())580 if paragraph.strip()581 )582 583 584def _feature_set_anchor(name: str) -> str:585 return "feature-set-" + _slug(name)586 587 588def _resolve_related_entity(589 reference: str, entity: cpdocs.model.ApiEntity, graph: cpdocs.model.ApiGraph590) -> cpdocs.model.ApiEntity | None:591 normalized = reference.strip()592 if not normalized:593 return None594 595 if "::" in normalized or "." in normalized:596 for candidate in graph.entities.values():597 if candidate.qualified_name == normalized or candidate.name == normalized:598 return candidate599 600 if entity.parent and entity.parent in graph.entities:601 parent = graph.entities[entity.parent]602 for child_id in parent.children:603 child = graph.entities[child_id]604 if child.name == normalized:605 return child606 607 matches = [candidate for candidate in graph.entities.values() if candidate.name == normalized]608 return matches[0] if len(matches) == 1 else None609 610 611def _documentation_blocks(612 entity: cpdocs.model.ApiEntity, graph: cpdocs.model.ApiGraph613) -> tuple[str, list[tuple[str, cpdocs.model.ApiEntity | None]]]:614 related_names = list(entity.related)615 paragraphs: list[str] = []616 for block in re.split(r"\n\s*\n", entity.documentation.strip()):617 paragraph = block.strip()618 if not paragraph:619 continue620 if paragraph.startswith("CPDOCS-API-RELATES-TO:"):621 payload = paragraph.split(":", 1)[1]622 for item in re.split(r"\s*,\s*", payload.strip()):623 if item and item not in related_names:624 related_names.append(item)625 continue626 paragraphs.append(paragraph)627 text = "\n\n".join(paragraphs)628 related = [(name, _resolve_related_entity(name, entity, graph)) for name in related_names]629 return _paragraphs(text), related630 631 632def _feature_set_display_name(name: str) -> str:633 if name.casefold() in {"cpu", "cuda", "hip", "mpi", "sycl"}:634 return name.upper()635 return name636 637 638def _member_summary_spelling(entity: cpdocs.model.ApiEntity) -> str:639 return cpdocs.languages.rendering_for(entity.language).member_summary(entity)640 641 642def _relative_link(source: pathlib.Path, target: pathlib.Path) -> str:643 import posixpath644 645 def output_directory(document: pathlib.Path) -> pathlib.Path:646 if document.name == "index.md":647 return document.parent648 return document.with_suffix("")649 650 source_dir = output_directory(source)651 target_dir = output_directory(target)652 value = posixpath.relpath(target_dir.as_posix(), source_dir.as_posix())653 return "./" if value == "." else value.rstrip("/") + "/"654 655 656def _kind_marker(kind: str, language: str) -> str:657 return cpdocs.languages.kind_marker(kind, language)