cpdocs API documentation
Project documentation Docs

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)