cpdocs 0.1.0__py3-none-any.whl

cpdocs/share/cmake/cpdocs.cmake

@@ -0,0 +1,464 @@
+# --------------------------------------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+# --------------------------------------------------------------------------------------------------
+# CMake implementation of the cpdocs build-system contract.
+#
+# cpdocs injects this file with -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES and passes its request with
+# -DCPDOCS_REQUEST. A project declares what it documents:
+#
+#   cpdocs_features(<axis> [VALUES <value>...])
+#   cpdocs_variant(<name> [PRIMARY] [<axis> <value>...]...)
+#   cpdocs_api(UNIT <id> LANGUAGE <c|cpp|python|rust>
+#              [TARGET <target>] [API <dir>...] [GENERATED <dir>...]
+#              [STANDARD <std>] [DEFINE <definition>...] [INCLUDE <dir>...]
+#              [PACKAGE <python package>] [RUSTDOC_JSON <file>] [DEPENDS <target>...])
+#
+# Feature axes follow the besa_feature convention: the axis variable holds the selected values, the
+# <axis>_ARRAY variable holds the valid values, and "none" / "all" select nothing or everything.
+#
+# At the end of the top-level CMakeLists.txt the adapter answers the request:
+#
+#   describe  writes the describe manifest directly;
+#   variant   generates the per-unit description and a `cpdocs-prepare` target that builds the
+#             declared dependencies and then converts that description into the variant manifest.
+# --------------------------------------------------------------------------------------------------
+
+include_guard(GLOBAL)
+if(CMAKE_VERSION VERSION_LESS 3.24)
+  message(FATAL_ERROR "cpdocs.cmake needs CMake 3.24 or newer")
+endif()
+# Everything below, including the functions it defines, uses modern policies regardless of the
+# project's own cmake_minimum_required.
+cmake_policy(PUSH)
+cmake_policy(VERSION 3.24)
+
+# --------------------------------------------------------------------------------------------------
+# JSON helpers (shared by configure and script mode)
+# --------------------------------------------------------------------------------------------------
+function(_cpdocs_json_string out value)
+  string(REPLACE "\\" "\\\\" value "${value}")
+  string(REPLACE "\"" "\\\"" value "${value}")
+  string(REPLACE "\t" "\\t" value "${value}")
+  string(REPLACE "\n" "\\n" value "${value}")
+  set(${out} "\"${value}\"" PARENT_SCOPE)
+endfunction()
+
+# Build a JSON array of strings from the remaining arguments.
+function(_cpdocs_json_array out)
+  set(items "")
+  foreach(value IN LISTS ARGN)
+    _cpdocs_json_string(quoted "${value}")
+    list(APPEND items "${quoted}")
+  endforeach()
+  list(JOIN items ", " joined)
+  set(${out} "[${joined}]" PARENT_SCOPE)
+endfunction()
+
+# --------------------------------------------------------------------------------------------------
+# Script mode: convert the generated unit description into the variant manifest
+# --------------------------------------------------------------------------------------------------
+if(CMAKE_SCRIPT_MODE_FILE)
+  if(NOT DEFINED CPDOCS_CONVERT OR NOT DEFINED CPDOCS_OUTPUT)
+    message(FATAL_ERROR "cpdocs.cmake: script mode needs CPDOCS_CONVERT and CPDOCS_OUTPUT")
+  endif()
+  file(STRINGS "${CPDOCS_CONVERT}" lines)
+
+  set(variant "")
+  set(features "")
+  set(units "")
+  set(unit "")
+
+  macro(_cpdocs_flush_unit)
+    if(NOT unit STREQUAL "")
+      _cpdocs_json_string(id "${unit}")
+      _cpdocs_json_string(lang "${u_language}")
+      set(roots "")
+      foreach(path IN LISTS u_api)
+        _cpdocs_json_string(quoted "${path}")
+        list(APPEND roots "{\"path\": ${quoted}}")
+      endforeach()
+      foreach(path IN LISTS u_generated)
+        _cpdocs_json_string(quoted "${path}")
+        list(APPEND roots "{\"path\": ${quoted}, \"generated\": true}")
+      endforeach()
+      list(JOIN roots ", " roots)
+      set(entry "{\"id\": ${id}, \"language\": ${lang}, \"api\": [${roots}]")
+      if(u_language STREQUAL "c" OR u_language STREQUAL "cpp")
+        list(REMOVE_DUPLICATES u_include)
+        list(REMOVE_DUPLICATES u_system)
+        list(REMOVE_DUPLICATES u_define)
+        _cpdocs_json_string(standard "${u_standard}")
+        _cpdocs_json_array(include ${u_include})
+        _cpdocs_json_array(system ${u_system})
+        _cpdocs_json_array(define ${u_define})
+        _cpdocs_json_array(flags ${u_flags})
+        string(APPEND entry ", \"parse\": {\"standard\": ${standard}, \"include\": ${include}, "
+          "\"system-include\": ${system}, \"define\": ${define}, \"flags\": ${flags}}")
+      elseif(u_language STREQUAL "python")
+        _cpdocs_json_string(package "${u_package}")
+        string(APPEND entry ", \"package\": ${package}")
+      elseif(u_language STREQUAL "rust")
+        _cpdocs_json_string(rustdoc "${u_rustdoc}")
+        string(APPEND entry ", \"rustdoc-json\": ${rustdoc}")
+      endif()
+      string(APPEND entry "}")
+      list(APPEND units "${entry}")
+    endif()
+    foreach(field language api generated standard include system define flags package rustdoc)
+      set(u_${field} "")
+    endforeach()
+  endmacro()
+
+  foreach(line IN LISTS lines)
+    string(FIND "${line}" "=" split)
+    if(split LESS 1)
+      continue()
+    endif()
+    string(SUBSTRING "${line}" 0 ${split} key)
+    math(EXPR start "${split} + 1")
+    string(SUBSTRING "${line}" ${start} -1 value)
+    if(key STREQUAL "variant")
+      set(variant "${value}")
+    elseif(key STREQUAL "feature")
+      string(FIND "${value}" "=" split)
+      string(SUBSTRING "${value}" 0 ${split} axis)
+      math(EXPR start "${split} + 1")
+      string(SUBSTRING "${value}" ${start} -1 selected)
+      string(REPLACE "," ";" selected "${selected}")
+      _cpdocs_json_string(axis "${axis}")
+      _cpdocs_json_array(selected ${selected})
+      list(APPEND features "${axis}: ${selected}")
+    elseif(key STREQUAL "unit")
+      _cpdocs_flush_unit()
+      set(unit "${value}")
+    elseif(value STREQUAL "")
+      continue()
+    elseif(key STREQUAL "standard" OR key STREQUAL "language" OR key STREQUAL "package"
+        OR key STREQUAL "rustdoc")
+      set(u_${key} "${value}")
+    else()
+      list(APPEND u_${key} "${value}")
+    endif()
+  endforeach()
+  _cpdocs_flush_unit()
+
+  list(JOIN features ", " features)
+  list(JOIN units ", " units)
+  _cpdocs_json_string(variant "${variant}")
+  file(WRITE "${CPDOCS_OUTPUT}" "{\n  \"cpdocs-manifest\": 1,\n  \"kind\": \"variant\",\n"
+    "  \"variant\": ${variant},\n  \"features\": {${features}},\n  \"units\": [${units}]\n}\n")
+  cmake_policy(POP)
+  return()
+endif()
+
+# --------------------------------------------------------------------------------------------------
+# Configure mode
+# --------------------------------------------------------------------------------------------------
+set(CPDOCS_MODULE "${CMAKE_CURRENT_LIST_FILE}" CACHE INTERNAL "cpdocs CMake adapter")
+set(CPDOCS_CONFIGURE_ARGS "" CACHE STRING
+  "Extra cache arguments forwarded to every cpdocs variant configuration")
+
+function(cpdocs_features axis)
+  cmake_parse_arguments(PARSE_ARGV 1 arg "" "" "VALUES")
+  if(arg_VALUES)
+    set(values ${arg_VALUES})
+  elseif(DEFINED ${axis}_ARRAY)
+    set(values ${${axis}_ARRAY})
+  else()
+    message(FATAL_ERROR "cpdocs_features(${axis}): give VALUES or declare the axis first")
+  endif()
+  set_property(GLOBAL APPEND PROPERTY CPDOCS_AXES "${axis}")
+  set_property(GLOBAL PROPERTY CPDOCS_AXIS_${axis}_VALUES "${values}")
+endfunction()
+
+function(cpdocs_variant name)
+  get_property(axes GLOBAL PROPERTY CPDOCS_AXES)
+  set(primary FALSE)
+  set(axis "")
+  foreach(token IN LISTS ARGN)
+    if(token STREQUAL "PRIMARY")
+      set(primary TRUE)
+    elseif(token IN_LIST axes)
+      set(axis "${token}")
+      set(spelling_${axis} "")
+    elseif(axis STREQUAL "")
+      message(FATAL_ERROR "cpdocs_variant(${name}): ${token} is not a declared feature axis")
+    else()
+      list(APPEND spelling_${axis} "${token}")
+    endif()
+  endforeach()
+  set_property(GLOBAL APPEND PROPERTY CPDOCS_VARIANTS "${name}")
+  set_property(GLOBAL PROPERTY CPDOCS_VARIANT_${name}_PRIMARY ${primary})
+  foreach(axis IN LISTS axes)
+    if(DEFINED spelling_${axis})
+      set_property(GLOBAL PROPERTY CPDOCS_VARIANT_${name}_AXIS_${axis} "${spelling_${axis}}")
+    endif()
+  endforeach()
+endfunction()
+
+function(cpdocs_api)
+  cmake_parse_arguments(PARSE_ARGV 0 arg "" "UNIT;LANGUAGE;TARGET;STANDARD;PACKAGE;RUSTDOC_JSON"
+    "API;GENERATED;DEFINE;INCLUDE;DEPENDS")
+  if(NOT arg_UNIT OR NOT arg_LANGUAGE)
+    message(FATAL_ERROR "cpdocs_api needs UNIT and LANGUAGE")
+  endif()
+  set(unit "${arg_UNIT}")
+  set(api "")
+  foreach(path IN LISTS arg_API)
+    cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" NORMALIZE)
+    list(APPEND api "${path}")
+  endforeach()
+  set(generated "")
+  foreach(path IN LISTS arg_GENERATED)
+    cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" NORMALIZE)
+    list(APPEND generated "${path}")
+  endforeach()
+  set(include "")
+  foreach(path IN LISTS arg_INCLUDE)
+    cmake_path(ABSOLUTE_PATH path BASE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" NORMALIZE)
+    list(APPEND include "${path}")
+  endforeach()
+  set(rustdoc "")
+  if(arg_RUSTDOC_JSON)
+    set(rustdoc "${arg_RUSTDOC_JSON}")
+    cmake_path(ABSOLUTE_PATH rustdoc BASE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" NORMALIZE)
+  endif()
+  set_property(GLOBAL APPEND PROPERTY CPDOCS_UNITS "${unit}")
+  foreach(field LANGUAGE TARGET STANDARD PACKAGE DEFINE DEPENDS)
+    set_property(GLOBAL PROPERTY CPDOCS_UNIT_${unit}_${field} "${arg_${field}}")
+  endforeach()
+  set_property(GLOBAL PROPERTY CPDOCS_UNIT_${unit}_API "${api}")
+  set_property(GLOBAL PROPERTY CPDOCS_UNIT_${unit}_GENERATED "${generated}")
+  set_property(GLOBAL PROPERTY CPDOCS_UNIT_${unit}_INCLUDE "${include}")
+  set_property(GLOBAL PROPERTY CPDOCS_UNIT_${unit}_RUSTDOC "${rustdoc}")
+endfunction()
+
+# Selected values of an axis in the current configuration, with none/all resolved.
+function(_cpdocs_resolve out axis spelling)
+  get_property(values GLOBAL PROPERTY CPDOCS_AXIS_${axis}_VALUES)
+  if("all" IN_LIST spelling)
+    set(${out} "${values}" PARENT_SCOPE)
+  elseif("none" IN_LIST spelling)
+    set(${out} "" PARENT_SCOPE)
+  else()
+    set(${out} "${spelling}" PARENT_SCOPE)
+  endif()
+endfunction()
+
+# The C or C++ standard a target asks its consumers for, from its compile features.
+function(_cpdocs_standard out target language)
+  set(prefix "cxx_std_")
+  set(flag "c++")
+  if(language STREQUAL "c")
+    set(prefix "c_std_")
+    set(flag "c")
+  endif()
+  get_target_property(features ${target} INTERFACE_COMPILE_FEATURES)
+  set(best "")
+  foreach(feature IN LISTS features)
+    if(feature MATCHES "^${prefix}([0-9]+)$")
+      set(number "${CMAKE_MATCH_1}")
+      if(best STREQUAL "" OR number GREATER best)
+        set(best "${number}")
+      endif()
+    endif()
+  endforeach()
+  if(best STREQUAL "")
+    set(${out} "" PARENT_SCOPE)
+  else()
+    set(${out} "${flag}${best}" PARENT_SCOPE)
+  endif()
+endfunction()
+
+function(_cpdocs_describe manifest)
+  get_property(axes GLOBAL PROPERTY CPDOCS_AXES)
+  get_property(units GLOBAL PROPERTY CPDOCS_UNITS)
+  get_property(variants GLOBAL PROPERTY CPDOCS_VARIANTS)
+  if(NOT units)
+    message(FATAL_ERROR "cpdocs: the project declares no cpdocs_api() units")
+  endif()
+  if(NOT variants)
+    set(variants default)
+    set_property(GLOBAL PROPERTY CPDOCS_VARIANT_default_PRIMARY TRUE)
+  endif()
+  set(has_primary FALSE)
+  foreach(name IN LISTS variants)
+    get_property(primary GLOBAL PROPERTY CPDOCS_VARIANT_${name}_PRIMARY)
+    if(primary)
+      set(has_primary TRUE)
+    endif()
+  endforeach()
+  if(NOT has_primary)
+    list(GET variants 0 first)
+    set_property(GLOBAL PROPERTY CPDOCS_VARIANT_${first}_PRIMARY TRUE)
+  endif()
+
+  set(feature_entries "")
+  foreach(axis IN LISTS axes)
+    get_property(values GLOBAL PROPERTY CPDOCS_AXIS_${axis}_VALUES)
+    _cpdocs_json_string(key "${axis}")
+    _cpdocs_json_array(values ${values})
+    list(APPEND feature_entries "${key}: {\"values\": ${values}}")
+  endforeach()
+  list(JOIN feature_entries ", " feature_entries)
+
+  set(unit_entries "")
+  foreach(unit IN LISTS units)
+    get_property(language GLOBAL PROPERTY CPDOCS_UNIT_${unit}_LANGUAGE)
+    _cpdocs_json_string(id "${unit}")
+    _cpdocs_json_string(language "${language}")
+    list(APPEND unit_entries "{\"id\": ${id}, \"language\": ${language}}")
+  endforeach()
+  list(JOIN unit_entries ", " unit_entries)
+
+  set(common "${CMAKE_COMMAND}" -S "{source}" -B "{build}" -G "${CMAKE_GENERATOR}"
+    "-DCPDOCS_REQUEST={request}" "-DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=${CPDOCS_MODULE}")
+  if(CMAKE_BUILD_TYPE)
+    list(APPEND common "-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}")
+  endif()
+  if(CMAKE_TOOLCHAIN_FILE)
+    list(APPEND common "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
+  endif()
+  list(APPEND common ${CPDOCS_CONFIGURE_ARGS})
+  _cpdocs_json_array(build "${CMAKE_COMMAND}" --build "{build}" --target cpdocs-prepare)
+
+  set(variant_entries "")
+  foreach(name IN LISTS variants)
+    get_property(primary GLOBAL PROPERTY CPDOCS_VARIANT_${name}_PRIMARY)
+    _cpdocs_json_array(configure ${common})
+    string(REGEX REPLACE "]$" "" configure "${configure}")
+    set(selected_entries "")
+    foreach(axis IN LISTS axes)
+      get_property(pinned GLOBAL PROPERTY CPDOCS_VARIANT_${name}_AXIS_${axis} SET)
+      if(pinned)
+        get_property(spelling GLOBAL PROPERTY CPDOCS_VARIANT_${name}_AXIS_${axis})
+      else()
+        set(spelling "${${axis}}")
+      endif()
+      if(spelling STREQUAL "")
+        set(spelling none)
+      endif()
+      _cpdocs_resolve(selected "${axis}" "${spelling}")
+      _cpdocs_json_string(argument "-D${axis}=${spelling}")
+      string(APPEND configure ", ${argument}")
+      _cpdocs_json_string(key "${axis}")
+      _cpdocs_json_array(selected ${selected})
+      list(APPEND selected_entries "${key}: ${selected}")
+    endforeach()
+    list(JOIN selected_entries ", " selected_entries)
+    string(APPEND configure "]")
+    _cpdocs_json_string(quoted "${name}")
+    if(primary)
+      set(primary true)
+    else()
+      set(primary false)
+    endif()
+    string(CONCAT entry "{\"name\": ${quoted}, \"primary\": ${primary}, "
+      "\"features\": {${selected_entries}}, \"commands\": [${configure}, ${build}]}")
+    if(NOT variant_entries STREQUAL "")
+      string(APPEND variant_entries ",\n    ")
+    endif()
+    string(APPEND variant_entries "${entry}")
+  endforeach()
+
+  _cpdocs_json_string(project_name "${CMAKE_PROJECT_NAME}")
+  _cpdocs_json_string(project_version "${CMAKE_PROJECT_VERSION}")
+  _cpdocs_json_string(generator "cpdocs.cmake / CMake ${CMAKE_VERSION}")
+  file(WRITE "${manifest}" "{\n  \"cpdocs-manifest\": 1,\n  \"kind\": \"describe\",\n"
+    "  \"generator\": ${generator},\n"
+    "  \"project\": {\"name\": ${project_name}, \"version\": ${project_version}},\n"
+    "  \"features\": {${feature_entries}},\n  \"units\": [${unit_entries}],\n"
+    "  \"variants\": [\n    ${variant_entries}\n  ]\n}\n")
+endfunction()
+
+function(_cpdocs_variant name manifest)
+  get_property(axes GLOBAL PROPERTY CPDOCS_AXES)
+  get_property(units GLOBAL PROPERTY CPDOCS_UNITS)
+  get_property(variants GLOBAL PROPERTY CPDOCS_VARIANTS)
+  if(variants AND NOT name IN_LIST variants)
+    message(FATAL_ERROR "cpdocs: the project declares no variant '${name}'")
+  endif()
+
+  # The unit description is written with generator expressions, so target usage requirements are
+  # evaluated by CMake itself, and converted to JSON by `cpdocs-prepare` in script mode.
+  set(content "variant=${name}\n")
+  foreach(axis IN LISTS axes)
+    set(spelling "${${axis}}")
+    if(spelling STREQUAL "")
+      set(spelling none)
+    endif()
+    _cpdocs_resolve(selected "${axis}" "${spelling}")
+    list(JOIN selected "," selected)
+    string(APPEND content "feature=${axis}=${selected}\n")
+  endforeach()
+
+  set(dependencies "")
+  foreach(unit IN LISTS units)
+    foreach(field LANGUAGE TARGET STANDARD PACKAGE DEFINE DEPENDS API GENERATED INCLUDE RUSTDOC)
+      get_property(u_${field} GLOBAL PROPERTY CPDOCS_UNIT_${unit}_${field})
+    endforeach()
+    list(APPEND dependencies ${u_DEPENDS})
+    string(APPEND content "unit=${unit}\nlanguage=${u_LANGUAGE}\n")
+    foreach(path IN LISTS u_API)
+      string(APPEND content "api=${path}\n")
+    endforeach()
+    foreach(path IN LISTS u_GENERATED)
+      string(APPEND content "generated=${path}\n")
+    endforeach()
+    if(u_LANGUAGE STREQUAL "python")
+      string(APPEND content "package=${u_PACKAGE}\n")
+    elseif(u_LANGUAGE STREQUAL "rust")
+      string(APPEND content "rustdoc=${u_RUSTDOC}\n")
+    else()
+      if(u_STANDARD STREQUAL "" AND NOT u_TARGET STREQUAL "")
+        _cpdocs_standard(u_STANDARD "${u_TARGET}" "${u_LANGUAGE}")
+      endif()
+      string(APPEND content "standard=${u_STANDARD}\n")
+      foreach(path IN LISTS u_INCLUDE)
+        string(APPEND content "include=${path}\n")
+      endforeach()
+      foreach(definition IN LISTS u_DEFINE)
+        string(APPEND content "define=${definition}\n")
+      endforeach()
+      if(NOT u_TARGET STREQUAL "")
+        foreach(pair "include;INTERFACE_INCLUDE_DIRECTORIES"
+            "system;INTERFACE_SYSTEM_INCLUDE_DIRECTORIES"
+            "define;INTERFACE_COMPILE_DEFINITIONS" "flags;INTERFACE_COMPILE_OPTIONS")
+          list(GET pair 0 key)
+          list(GET pair 1 name)
+          set(property "$<TARGET_PROPERTY:${u_TARGET},${name}>")
+          string(APPEND content "${key}=$<JOIN:${property},\n${key}=>\n")
+        endforeach()
+      endif()
+    endif()
+  endforeach()
+
+  set(description "${CMAKE_BINARY_DIR}/cpdocs/units-$<CONFIG>.txt")
+  file(GENERATE OUTPUT "${description}" CONTENT "${content}")
+  add_custom_target(cpdocs-prepare
+    COMMAND "${CMAKE_COMMAND}" "-DCPDOCS_CONVERT=${description}" "-DCPDOCS_OUTPUT=${manifest}"
+      -P "${CPDOCS_MODULE}"
+    VERBATIM)
+  if(dependencies)
+    add_dependencies(cpdocs-prepare ${dependencies})
+  endif()
+endfunction()
+
+function(_cpdocs_finalize)
+  file(READ "${CPDOCS_REQUEST}" request)
+  string(JSON phase GET "${request}" phase)
+  string(JSON manifest GET "${request}" manifest)
+  if(phase STREQUAL "describe")
+    _cpdocs_describe("${manifest}")
+  else()
+    string(JSON variant GET "${request}" variant)
+    _cpdocs_variant("${variant}" "${manifest}")
+  endif()
+endfunction()
+
+if(DEFINED CPDOCS_REQUEST AND NOT CPDOCS_REQUEST STREQUAL "")
+  cmake_language(DEFER DIRECTORY "${CMAKE_SOURCE_DIR}" CALL _cpdocs_finalize)
+endif()
+
+cmake_policy(POP)

cpdocs/versioning.py

@@ -0,0 +1,201 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Git-ref selection for cpdocs' versioned API site.
+
+Branches are named explicitly (glob patterns allowed) and are always built. Tags are chosen by a
+selector. Branch names are matched against local branches and, for CI clones that only carry the
+checked-out branch locally, against remote-tracking branches as well.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from packaging.version import InvalidVersion, Version
+
+_RANGE_PART = re.compile(r"^(>=|<=|==|!=|>|<)\s*(.+)$")
+
+
+def _git_ref_names(project_root: Path, namespace: str) -> list[str]:
+    result = subprocess.run(
+        ["git", "for-each-ref", "--format=%(refname:short)", f"refs/{namespace}/"],
+        cwd=project_root,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if result.returncode != 0:
+        raise RuntimeError("cpdocs version selection requires a readable Git repository")
+    return [line for line in result.stdout.splitlines() if line]
+
+
+def _versioned_tags(project_root: Path) -> list[tuple[Version, str]]:
+    values: list[tuple[Version, str]] = []
+    for tag in _git_ref_names(project_root, "tags"):
+        try:
+            parsed = Version(tag)
+        except InvalidVersion:
+            continue
+        values.append((parsed, tag))
+    return sorted(values, key=lambda item: (item[0], item[1]))
+
+
+def _version_in_range(version_value: Version, expression: str) -> bool:
+    comparators = [part.strip() for part in expression.split(",") if part.strip()]
+    if not comparators:
+        raise RuntimeError("cpdocs version range must contain at least one comparator")
+    for comparator in comparators:
+        match = _RANGE_PART.fullmatch(comparator)
+        if match is None:
+            raise RuntimeError(
+                f"invalid cpdocs version range comparator {comparator!r}; use forms such as >=0.2,<0.6"
+            )
+        operator, raw_version = match.groups()
+        try:
+            boundary = Version(raw_version.strip())
+        except InvalidVersion as error:
+            raise RuntimeError(f"invalid cpdocs version {raw_version!r} in range") from error
+        relation = {
+            ">=": version_value >= boundary,
+            "<=": version_value <= boundary,
+            "==": version_value == boundary,
+            "!=": version_value != boundary,
+            ">": version_value > boundary,
+            "<": version_value < boundary,
+        }[operator]
+        if not relation:
+            return False
+    return True
+
+
+@dataclass(frozen=True)
+class SelectedRef:
+    """One version to build: its label, its kind and the Git object to check out.
+
+    ``checkout`` is ``None`` when the label is the branch currently checked out, in which case the
+    working tree itself is documented (uncommitted changes included).
+    """
+
+    name: str
+    kind: str
+    checkout: str | None
+
+
+def select_tags(project_root: Path, value: str) -> list[str]:
+    """Return tag names chosen by a selector, newest first."""
+
+    value = value.strip()
+    if value == "none":
+        return []
+    tags = _versioned_tags(project_root)
+    if value == "all":
+        return [tag for _version, tag in reversed(tags)]
+    if value.startswith("latest:"):
+        try:
+            count = int(value.removeprefix("latest:").strip())
+        except ValueError as error:
+            raise RuntimeError(f"invalid cpdocs latest selector {value!r}") from error
+        if count < 1:
+            raise RuntimeError("cpdocs latest selector must request at least one version")
+        return [tag for _version, tag in reversed(tags[-count:])]
+    if value.startswith("range:"):
+        expression = value.removeprefix("range:").strip()
+        return [tag for parsed, tag in reversed(tags) if _version_in_range(parsed, expression)]
+    if value.startswith("refs:"):
+        requested = [
+            item.strip() for item in value.removeprefix("refs:").split(",") if item.strip()
+        ]
+        if not requested:
+            raise RuntimeError("cpdocs refs selector must contain at least one tag")
+        known = set(_git_ref_names(project_root, "tags"))
+        unknown = [name for name in requested if name not in known]
+        if unknown:
+            raise RuntimeError("unknown cpdocs Git tags: " + ", ".join(unknown))
+        return requested
+    raise RuntimeError(
+        f"unsupported cpdocs tag selector {value!r}; expected all, none, latest:N, "
+        "range:<comparators>, or refs:<tag,...>"
+    )
+
+
+def _branches(project_root: Path) -> dict[str, str]:
+    """Map branch names to the ref that can be checked out, preferring local branches."""
+
+    values: dict[str, str] = {}
+    for remote_ref in _git_ref_names(project_root, "remotes"):
+        remote, _, name = remote_ref.partition("/")
+        if name and name != "HEAD":
+            values.setdefault(name, f"{remote}/{name}")
+    for name in _git_ref_names(project_root, "heads"):
+        values[name] = name
+    return values
+
+
+def current_branch(project_root: Path) -> str | None:
+    """Name of the checked-out branch, also in detached CI checkouts."""
+
+    for variable in ("CPDOCS_CURRENT_BRANCH", "GITHUB_HEAD_REF", "CI_COMMIT_BRANCH"):
+        value = os.environ.get(variable, "").strip()
+        if value:
+            return value
+    if os.environ.get("GITHUB_REF_TYPE") == "branch" and os.environ.get("GITHUB_REF_NAME"):
+        return os.environ["GITHUB_REF_NAME"]
+    result = subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=project_root,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+    )
+    value = result.stdout.strip()
+    return value or None
+
+
+def select_refs(project_root: Path, *, branches: tuple[str, ...], tags: str) -> list[SelectedRef]:
+    """Select every version to build: the configured branches first, then the selected tags."""
+
+    available = _branches(project_root)
+    current = current_branch(project_root)
+    selected: list[SelectedRef] = []
+    seen: set[str] = set()
+    for pattern in branches:
+        if any(character in pattern for character in "*?["):
+            matches = sorted(name for name in available if fnmatch.fnmatchcase(name, pattern))
+        elif pattern in available or pattern == current:
+            matches = [pattern]
+        else:
+            raise RuntimeError(
+                f"configured branch {pattern!r} does not exist locally or on a remote; "
+                "fetch it before building versions"
+            )
+        for name in matches:
+            if name in seen:
+                continue
+            seen.add(name)
+            checkout = None if name == current else available[name]
+            selected.append(SelectedRef(name=name, kind="branch", checkout=checkout))
+    for tag in select_tags(project_root, tags):
+        if tag in seen:
+            continue
+        seen.add(tag)
+        selected.append(SelectedRef(name=tag, kind="tag", checkout=f"refs/tags/{tag}"))
+    return selected
+
+
+def latest_tag(names: list[str]) -> str | None:
+    """Return the highest semantic version among ``names``."""
+
+    versions: list[tuple[Version, str]] = []
+    for name in names:
+        try:
+            versions.append((Version(name), name))
+        except InvalidVersion:
+            continue
+    return max(versions)[1] if versions else None