Links

View on PyPI

AI / Agents

Skills
llms.txt
llms-full.txt

gdtest-complete-docstrings

A synthetic test package demonstrating complete docstrings for objects that typically receive minimal documentation: constants, module-level variables, type aliases, TypeVars, and properties.

A connection-pool package whose public API is built from objects that typically get minimal docstrings: Final constants (MAX_CONNECTIONS, MIN_CONNECTIONS, SUPPORTED_BACKENDS), mutable module-level variables (timeout, retry_delay), TypeAlias declarations (ConnectionId, BackendName, PoolKey), TypeVar declarations (Sortable, Handler), properties (is_idle, is_closed, backend, connection_id), and the module docstring itself. Every object carries a complete docstring with summary, extended description, and relevant sections (Notes, Examples, Returns, %seealso). On the Reference page you should see Constants, Classes, and Functions sections with rich rendered docstrings throughout.

Source files

📁 gdtest_complete_docstrings/

📄 __init__.py

"""Connection pooling and lifecycle management.

This module owns the connection pool, the health-check loop, and
the retry logic that wraps individual queries. Most users interact
with it through `get_connection()` and the `Connection` context
manager; the pool configuration constants are exposed for tuning.

Notes
-----
The pool is process-global. Forking after the pool has been
initialized leads to shared file descriptors; use
`reinitialize()` in the child process.

%seealso Connection, get_connection
"""

__version__ = "0.1.0"
__all__ = [
    "MAX_CONNECTIONS",
    "MIN_CONNECTIONS",
    "SUPPORTED_BACKENDS",
    "timeout",
    "retry_delay",
    "ConnectionId",
    "BackendName",
    "PoolKey",
    "Sortable",
    "Handler",
    "Connection",
    "get_connection",
    "reinitialize",
]

from typing import Final, TypeAlias, TypeVar, Callable, Literal


# ── Constants ────────────────────────────────────────────────

MAX_CONNECTIONS: Final[int] = 128
"""Upper bound on simultaneous database connections.

Exceeding this limit raises `ConnectionPoolExhausted`. The
default of 128 matches the PostgreSQL `max_connections` default
so that a single application instance can saturate one server
without over-provisioning.

Notes
-----
Deployments behind a connection pooler (PgBouncer, Odyssey) can
safely raise this to 500 or more, since the pooler manages the
actual backend connection count.

%seealso MIN_CONNECTIONS, Connection
"""

MIN_CONNECTIONS: Final[int] = 4
"""Lower bound on warm connections kept in the pool.

The pool always keeps at least this many connections open, even
during idle periods. This avoids the latency spike that comes
from establishing a fresh connection on the first request after
an idle window.

Notes
-----
Set this to 0 in test environments where connection setup is
expensive and the pool is never actually used.

%seealso MAX_CONNECTIONS
"""

SUPPORTED_BACKENDS: Final[tuple[str, ...]] = (
    "postgresql",
    "mysql",
    "sqlite",
)
"""Database backends the pool can connect to.

Each backend name must match a registered driver in the driver
registry. Adding a new backend requires implementing the
`Driver` protocol and registering it before pool initialization.

Examples
--------
Check whether a backend is available before connecting:

```python
if "postgresql" in SUPPORTED_BACKENDS:
    conn = get_connection("postgresql")
```

%seealso get_connection, BackendName
"""


# ── Module-level variables ───────────────────────────────────

timeout: int = 30
"""Seconds to wait before abandoning a connection attempt.

Set this before calling any connection functions. Values below 1
are treated as "no timeout" (the attempt blocks indefinitely).
The default of 30 seconds suits most interactive use; batch
pipelines may want 120 or more.

Examples
--------
```python
import gdtest_complete_docstrings as pool

pool.timeout = 60  # generous timeout for batch jobs
```

%seealso retry_delay, get_connection
"""

retry_delay: float = 1.5
"""Seconds to wait between retry attempts after a failed connect.

An exponential backoff multiplier is applied on each subsequent
retry, so the actual delay doubles each time: 1.5, 3.0, 6.0,
and so on. Set to 0 to disable the delay entirely (useful in
tests).

Notes
-----
The maximum effective delay is capped at `timeout`; if the
cumulative delay would exceed the timeout, the pool gives up
immediately instead of sleeping.

%seealso timeout
"""


# ── Type aliases ─────────────────────────────────────────────

ConnectionId: TypeAlias = str
"""An opaque handle for a single pooled connection.

Connection IDs are generated by the pool and are unique within
the lifetime of the process. They appear in log messages and
health-check output, so they are strings rather than integers
for readability.

%seealso Connection, get_connection
"""

BackendName: TypeAlias = Literal[
    "postgresql", "mysql", "sqlite"
]
"""A supported database backend, as a string literal.

Using a `Literal` type rather than a plain `str` lets type
checkers catch misspelled backend names at analysis time instead
of at runtime.

%seealso SUPPORTED_BACKENDS, get_connection
"""

PoolKey: TypeAlias = tuple[BackendName, str, int]
"""A unique identifier for a connection pool instance.

The triple `(backend, host, port)` distinguishes pools that
target different servers. Two calls to `get_connection()` with
the same pool key reuse the same underlying pool.

%seealso BackendName, get_connection
"""


# ── TypeVar ──────────────────────────────────────────────────

Sortable = TypeVar("Sortable", bound="Connection")
"""A connection type that can be compared for priority ordering.

Any type substituted for `Sortable` must be a `Connection`
subclass. This is used internally by the priority queue that
schedules health checks: connections with the oldest last-used
timestamp are checked first.

Notes
-----
The bound is `Connection` rather than a protocol because the
priority comparison depends on internal state (`_last_used`)
that is not part of any public protocol.

%seealso Connection
"""

Handler = TypeVar("Handler", bound=Callable)
"""A callable that handles connection lifecycle events.

Handlers are registered with `Connection.on_close()` and
`Connection.on_error()`. The `Callable` bound ensures that
only callables can be registered, while leaving the signature
flexible enough for both synchronous and asynchronous handlers.

%seealso Connection
"""


# ── Class with properties ────────────────────────────────────

class Connection:
    """A managed database connection drawn from the pool.

    Connections track their own state (idle, active, closed) and
    expose that state through read-only properties. Use
    `get_connection()` to obtain one; call `close()` when
    finished.

    Parameters
    ----------
    backend
        Which database backend this connection targets.
    connection_id
        The pool-assigned unique identifier.

    %seealso get_connection, reinitialize
    """

    def __init__(
        self,
        backend: BackendName,
        connection_id: ConnectionId,
    ) -> None:
        self._backend = backend
        self._id = connection_id
        self._in_flight: int = 0
        self._closed: bool = False

    @property
    def is_idle(self) -> bool:
        """Whether the connection has no in-flight queries.

        Computed from the internal transaction counter, so this
        is always consistent even if queries are being submitted
        from another thread. An idle connection can be safely
        returned to the pool or closed.

        Returns
        -------
        bool
            `True` when no queries are running on this
            connection.

        %seealso is_closed, close
        """
        return self._in_flight == 0

    @property
    def is_closed(self) -> bool:
        """Whether the connection has been permanently closed.

        A closed connection cannot be reused. Attempting to
        execute a query on a closed connection raises
        `ConnectionClosedError`.

        Returns
        -------
        bool
            `True` after `close()` has been called.

        %seealso is_idle, close
        """
        return self._closed

    @property
    def backend(self) -> BackendName:
        """The database backend this connection targets.

        This is the backend name passed at construction time and
        does not change over the connection's lifetime. Useful
        for dispatching backend-specific SQL dialect adjustments.

        Returns
        -------
        BackendName
            One of the `SUPPORTED_BACKENDS` values.

        %seealso SUPPORTED_BACKENDS, BackendName
        """
        return self._backend

    @property
    def connection_id(self) -> ConnectionId:
        """The pool-assigned unique identifier for this connection.

        Appears in log output and health-check reports. Two
        connections never share an ID within the same process,
        even after one has been closed and garbage-collected.

        Returns
        -------
        ConnectionId
            A human-readable string identifier.

        %seealso ConnectionId
        """
        return self._id

    def close(self) -> None:
        """Close the connection and return it to the pool.

        After calling `close()`, `is_closed` returns `True` and
        any further operations on this connection raise
        `ConnectionClosedError`.

        %seealso is_closed, is_idle
        """
        self._closed = True


# ── Functions ────────────────────────────────────────────────

def get_connection(
    backend: BackendName = "postgresql",
    host: str = "localhost",
    port: int = 5432,
) -> Connection:
    """Obtain a connection from the pool.

    If a pool for the given `(backend, host, port)` triple already
    exists, a connection is drawn from it. Otherwise a new pool is
    created with `MIN_CONNECTIONS` warm connections.

    Parameters
    ----------
    backend
        Which database backend to connect to.
    host
        The server hostname or IP address.
    port
        The server port number.

    Returns
    -------
    Connection
        A ready-to-use connection.

    Raises
    ------
    ConnectionPoolExhausted
        If the pool has reached `MAX_CONNECTIONS`.
    TimeoutError
        If a connection cannot be established within `timeout`
        seconds.

    %seealso Connection, MAX_CONNECTIONS, timeout
    """
    return Connection(backend, f"{host}:{port}:0")


def reinitialize() -> None:
    """Reset the global connection pool.

    Call this after `os.fork()` to avoid sharing file
    descriptors between parent and child processes. All existing
    connections are closed and new ones are established.

    Notes
    -----
    This is a no-op if the pool has not been initialized yet.

    %seealso get_connection, MIN_CONNECTIONS
    """
    pass

📄 README.md

# gdtest-complete-docstrings

A synthetic test package demonstrating complete docstrings for
objects that typically receive minimal documentation: constants,
module-level variables, type aliases, TypeVars, and properties.

📄 great-docs.yml generated

# Great Docs Configuration
# See https://posit-dev.github.io/great-docs/user-guide/configuration.html
#
# Every option appears below at its default value, with the values it accepts
# documented above it. Set only what you want to change: an option you leave
# out or commented out keeps its default.

# Module Name
# -----------
# Importable module name, when it differs from the project name
# (e.g. project 'py-yaml12' imports as 'yaml12').
# : null - (default) auto-detect
# : type(str) - the module name
# module: null

# Display Name
# ------------
# Display name for your package in the site navbar/title. Use this for a
# marketing/presentation name (e.g. 'My Package').
# : null - (default) the actual package name (e.g. 'my_package' or 'my-package')
# : type(str) - the name to display
# display_name: null

# Project Type
# ------------
# Primary ecosystem(s) the project belongs to. Controls which
# ecosystem-specific links and features are active by default.
# : python - (default) Python package; enables the PyPI link
# : go - Go CLI/library; disables the PyPI link by default
# : rust - Rust CLI/library; disables the PyPI link by default
# : type(list) - mixed project, e.g. [python, go]
# project_type: python

# Docstring Parser
# ----------------
# The docstring format used in your package. Auto-detected during
# initialization, but can be overridden here.
# : numpy - (default) numpydoc style
# : google - Google style
# : sphinx - Sphinx/reStructuredText style
parser: numpy

# Dynamic Introspection
# ---------------------
# How the renderer inspects your package. Auto-detected during initialization
# based on what works for your package, but can be overridden here.
# : true - (default) runtime introspection; more accurate for complex packages
# : false - static analysis only; better for packages with cyclic aliases
dynamic: true

# Jupyter Kernel
# --------------
# Jupyter kernel to use for executing code cells in .qmd files.
# This is set at the project level so it applies to all pages, including
# auto-generated API reference pages. Can be overridden in individual .qmd
# file frontmatter if needed for special cases.
# jupyter: python3

# Exclusions
# ----------
# Items to exclude from auto-documentation (affects 'init' and 'scan')
# exclude:
#   - InternalClass
#   - helper_function
# exclude: []

# Names to force-include even if they match AUTO_EXCLUDE
# auto_include: []

# Bypass the built-in AUTO_EXCLUDE list entirely
# no_auto_exclude: false

# PyPI Link
# ---------
# : null - (default) link to pypi.org for Python projects, no link otherwise
# : true - auto-detect the package name and link to pypi.org
# : false - disable the PyPI link
# : type(str) - a custom package index URL
# pypi: https://artifactory.example.com/pkg
# pypi: null

# GitHub Integration
# ------------------
# GitHub repository URL override (e.g. "https://github.com/owner/repo").
# repo: null

# GitHub link style
# : widget - (default) a widget showing the stars count
# : icon - a simple icon
# github_style: widget

# Site URL
# --------
# Canonical address of the deployed docs site. Used for skills-page install
# commands, .well-known/ discovery, sitemaps, and subdirectory deployments;
# also sets website.site-url in _quarto.yml.
# site_url: null

# Source Link Configuration
# -------------------------
# source:
#   enabled: true              # Enable/disable source links (default: true)
#   branch: null               # Git branch/tag to link to (default: auto-detect)
#   path: null                 # Custom source path for monorepos (default: auto-detect)
#   placement: usage           # Where to place the link: "usage" (default) or "title"

# Sidebar Filter
# --------------
# sidebar_filter:
#   enabled: true              # Enable/disable filter (default: true)
#   min_items: 20              # Minimum items before showing filter (default: 20)

# Marimo Notebooks
# ----------------
# Embed interactive WASM notebooks via marimo islands. `marimo: true` is
# shorthand for `enabled: true`.
# marimo:
#   enabled: false             # Enable marimo island notebooks
#   version: null              # @marimo-team/islands CDN version; defaults to the installed marimo version

# CLI Documentation
# -----------------
# cli:
#   enabled: false        # Enable CLI documentation
#   module: null          # e.g. my_package.cli; auto-detected
#   name: null            # Click command object; auto-detected
#   title: null           # Optional index page + sidebar title
#   desc: null            # Optional intro paragraph atop the index page
#   # sections: explicit grouping/ordering (omit = auto by code order). Example:
#   #   sections:
#   #     - title: "Project setup"
#   #       desc: "Create and configure a project."
#   #       contents: [init, config]
#   #     - title: Building
#   #       contents: [build, preview]
#   sections: []

# Go CLI Documentation
# --------------------
# Builds the Go binary and extracts its command tree via --help. Works with any
# Go CLI (Cobra, urfave/cli, ...) whose subcommands support --help.
# go_cli:
#   enabled: false   # Enable Go CLI documentation (default: false)

# Rust CLI Documentation
# ----------------------
# Builds the Rust binary via cargo and extracts its command tree via --help.
# Works with any Rust CLI (clap, structopt, argh, ...) whose subcommands
# support --help.
# rust_cli:
#   enabled: false   # Enable Rust CLI documentation (default: false)

# MCP Server Documentation
# ------------------------
# Auto-generates reference pages from an MCP server's tool/resource/prompt
# definitions.
# mcp:
#   enabled: true          # Enable MCP server documentation
#   module: null           # Importable module path (e.g. "sweet.mcp")
#   server_var: null       # Variable name of the Server instance; auto-detected when null
#   name: null             # Display name override; defaults to the server name
#   # Manual tool categories (grouping on the index page). Example:
#   #   categories:
#   #     "Data tools": [load, save]
#   categories: {}

# Dark Mode Toggle
# ----------------
# Enable/disable the dark mode toggle in navbar (default: true)
# dark_mode_toggle: true

# Author Information
# ------------------
# Author metadata for display in the landing page sidebar and page attribution
# authors:
#   - name: "Your Name"
#     email: you@example.com
#     role: "Lead Developer"
#     affiliation: Organization
#     github: yourusername
#     homepage: https://yoursite.com
#     orcid: 0000-0002-1234-5678
#     image: https://github.com/yourusername.png  # Avatar (GitHub URL or local path)
# authors: []

# Funding
# -------
# Funding organization (copyright holder / funder).
# funding:
#   name: "Posit Software, PBC"
#   roles: ["Copyright holder", "funder"]
#   ror: https://ror.org/03wc8by49
# funding: null

# Site Settings
# -------------
# Forwarded to _quarto.yml (format.html). `site` is a Quarto passthrough:
# its subtree is merged into `format.html`, so most valid `format.html` keys
# work here (e.g. `toc-title: "On this page"`). Reserved keys that great-docs
# manages itself and always overrides: `css` (copied and referenced by
# basename separately), `code-copy` (disabled — great-docs supplies its own
# copy-code widget), `html-table-processing` (disabled — required for GT
# table styling), and `mermaid` (fixed to the light theme — dark mode is
# handled via a CSS container). The great-docs page/UI settings that used to
# live here (language, show_dates, date_format, show_author, show_security)
# are top-level keys below; setting them under `site` still works and is
# lifted automatically.
# site:
#   theme: flatly            # Quarto theme
#   toc: true                # Show table of contents
#   toc-depth: 2             # TOC heading depth
#   html-math-method: katex  # HTML math renderer (e.g. mathjax)

# Page Metadata
# -------------
# Language for UI text (BCP 47 code, e.g., "en", "fr", "de", "ja", "zh-Hans")
# Translates navbar labels, widget text, tooltips, and accessibility labels
# language: en

# Show page timestamps in footer
# show_dates: false

# Date format (Python strftime)
# date_format: "%B %d, %Y"

# Show author attribution with dates
# show_author: true

# Show security policy page (from SECURITY.md)
# show_security: true

# Team Author
# -----------
# Optional catch-all author for auto-generated pages (reference, changelog, etc.)
# team_author:
#   name: "Project Team"
#   image: assets/team-avatar.png
#   url: https://github.com/org/project
# team_author: null

# Changelog (GitHub Releases)
# ---------------------------
# Auto-generate a Changelog page from GitHub Releases.
# changelog:
#   enabled: true              # Enable/disable changelog (default: true)
#   max_releases: 50           # Max releases to include (default: 50)

# Custom Sections
# ---------------
# Add custom page groups (examples, tutorials, blog, etc.) to the site.
# Each section gets a navbar link and a sidebar. An auto-generated
# card-based index page is created only when `index: true` is set;
# otherwise the navbar links directly to the first page in the section.
# If you provide your own index.qmd in the directory it is always used.
#
# sections:
#   - title: Examples            # Navbar link text
#     dir: examples              # Source directory (relative to project root)
#     index: true                # Generate card-based index page (default: false)
#     index_columns: 2           # Columns for image cards: 1 or 2 (default: 2)
#     navbar_after: "User Guide" # Place after this navbar item (optional)
#   - title: Tutorials
#     dir: tutorials             # No index — navbar links to first page
#   - title: Blog                # Blog section using Quarto's listing directive
#     dir: blog
#     type: blog                 # "blog" for Quarto listing, omit for card grid
# sections: []

# Custom Static Pages
# -------------------
# Add hand-written HTML pages that Great Docs should either wrap with the site
# shell (layout: passthrough) or copy through unchanged (layout: raw).
#
# : null - (default) discover the conventional `custom/` directory
# : false - disable discovery
# : type(str) - a single directory, e.g. marketing
# : type(list) - one entry per directory:
# custom_pages:
#   - dir: marketing             # Source directory (relative to project root)
#     output: py                 # URL/output prefix (optional; defaults to dir basename)
#   - dir: playgrounds
#     output: demos
# custom_pages: null

# Homepage
# --------
# : index - (default) separate homepage from the README / index source
# : user_guide - the first user-guide page becomes the landing page
# homepage: index

# User Guide
# ----------
# Where the User Guide .qmd files live, and optionally how they are ordered.
# : null - (default) look for user_guide/ in the project root
# : type(str) - a custom directory (relative to project root), e.g. docs/guides
# : type(list) - explicit section ordering and grouping:
# user_guide:
#   - section: "Get Started"
#     contents:
#       - text: Welcome
#         href: index.qmd
#       - quickstart.qmd
#       - installation.qmd
#   - section: "Advanced Topics"
#     contents:
#       - advanced-config.qmd
#       - extending.qmd
#
# File paths are relative to the user guide directory (no user_guide/ prefix).
# When using explicit ordering, numeric filename prefixes are preserved as-is.
# user_guide: null

# Bibliography & Citations
# ------------------------
# Project-level bibliography for [@citation-key] syntax. Paths are relative to
# the project root; the file(s) are copied into the build directory and wired
# into _quarto.yml so every page can cite without per-page frontmatter.
# : [] - (default) no bibliography
# : type(str) - a single file, e.g. docs/references.bib
# : type(list) - several files:
# bibliography:
#   - docs/references.bib
#   - docs/software.bib
# bibliography: []
# csl: docs/nature.csl                    # optional citation style
# csl: null

# API Reference Structure
# -----------------------
# Explicit control over API reference sections. If not provided, sections are
# auto-generated from discovered exports. Each section has a title, description,
# and list of contents.
#
# For classes, use `members: true` (default) to document methods inline on the
# class page, or `members: false` to exclude methods (you can place them
# explicitly elsewhere in the reference if needed).
#
# reference:
#   - title: "Core Classes"
#     desc: "Main classes for working with the package"
#     contents:
#       - name: MyClass
#         members: false       # Don't document methods here
#       - SimpleClass          # Methods documented inline (default)
#
#   - title: "Utility Functions"
#     desc: "Helper functions for common tasks"
#     contents:
#       - helper_func
#       - another_func
reference:
  - title: Classes
    desc: Main classes provided by the package
    contents:
      - Connection  # 1 method(s)

  - title: Functions
    desc: Utility functions
    contents:
      - get_connection
      - reinitialize

  - title: Constants
    desc: Module-level constants and data
    contents:
      - BackendName
      - ConnectionId
      - Handler
      - MAX_CONNECTIONS
      - MIN_CONNECTIONS
      - PoolKey
      - SUPPORTED_BACKENDS
      - Sortable
      - retry_delay
      - timeout

# Inline Methods
# --------------
# Whether class methods get their own pages or stay inline.
# : 5 - (default) inline up to 5 methods, split above that
# : true - always inline
# : false - always split
# : type(int) - inline up to N methods, split above N
# inline_methods: 5

# Logo & Favicon
# --------------
# A logo replaces the text title in the navbar.
# : type(str) - a single file used in both light and dark mode
# : type(map) - (default) light/dark variants, as below
# logo:
#   light: null            # null = no logo
#   dark: null             # dark-mode variant; falls back to `light` when null
#   show_title: false      # keep the text title alongside the logo

# Favicon.
# : null - (default) auto-generate from the logo, else skip
# : type(str) - a single file, e.g. assets/favicon.png
# : type(map) - one file per purpose:
# favicon:
#   icon: assets/icon.png
#   apple_touch: assets/apple-touch-icon.png
#   og_image: assets/og-image.png
# favicon: null

# Hero Section
# ------------
# Landing-page hero.
# : true - force enable
# : false - force disable
# : type(map) - (default) set the fields explicitly, as below
# hero:
#   enabled: null          # null = auto (on when a logo is set)
#   logo: null             # hero-specific logo; falls back to the navbar logo
#   logo_height: 200px     # max-height CSS value
#   name: null             # defaults to display_name; false hides it
#   tagline: null          # false hides it
#   badges: auto           # "auto" (from README), a list, or false
#   starfield: false       # interactive starfield animation

# Markdown Pages
# --------------
# Generate .md companions for every HTML page and show a copy/view-as-Markdown
# widget on each page.
# : false - disable both
# : type(map) - (default) set the fields explicitly, as below
# markdown_pages:
#   enabled: true   # Generate .md companions for every HTML page (default: true)
#   widget: true    # Show the copy/view-as-Markdown widget (requires enabled)

# Announcement Banner
# -------------------
# Site-wide banner above or below the navbar. Setting `content` enables it.
# : type(str) - the banner text (sets `content`)
# : type(map) - (default) set the fields explicitly, as below
# announcement:
#   content: null          # null = no banner; else the banner text (supports basic Markdown)
#   type: info             # "info" | "warning" | "success" | "danger"
#   dismissable: true      # Allow visitors to dismiss the banner
#   url: null              # Optional link the banner text points to
#   style: null            # Optional gradient preset (same names as navbar_style)
#   position: above-navbar # "above-navbar" (default) | "below-navbar"

# Versioning
# ----------
# Multi-version documentation; disabled when empty. Newest first.
# : [] - (default) single-version site
# : type(list) - tags only, e.g. ["0.3", "0.2", "0.1"], or a map per version:
# versions:
#   - tag: "0.3"
#     label: "0.3.0"
#     latest: true
# versions: []

# Version selector widget (enabled automatically when `versions` is non-empty).
# version_selector:
#   enabled: true             # Master switch for the widget
#   placement: navbar-right   # "navbar-right" | "navbar-left" | "sidebar-top"
#   show_eol: true            # Include end-of-life versions in the dropdown
#   warning_banner: true      # Show a banner on non-latest versions

# Floating version aliases.
# version_aliases:
#   latest: true   # /v/latest/ -> latest stable version
#   stable: true   # /v/stable/ -> same as latest
#   dev: true      # /v/dev/ -> prerelease version, if any

# Badge "new" expiry
# -----------------
# How long a page keeps its "new" status badge before it is considered old.
# : null - (default) no expiry; the badge persists
# : type(str) - a duration understood by parse_badge_expiry
#               (see user_guide/30-multi-version-docs.qmd)
# new_is_old: null

# Colors & Navbar
# ---------------
# Site-wide accent color; sets --gd-accent.
# : null - (default) the theme's own accent color
# : type(str) - any CSS color, used in both modes, e.g. "#3b82f6"
# : type(map) - per-mode:
# accent_color:
#   light: "#3b82f6"
#   dark: "#60a5fa"
# accent_color: null

# Navbar gradient preset.
# : null - (default) no gradient
# : type(str) - a preset name, e.g. sky, peach, lilac
# navbar_style: null

# Navbar solid background color. Text color is chosen automatically for
# contrast (APCA). Overridden when navbar_style is set.
# : null - (default) the theme's own navbar color
# : type(str) - any CSS color, used in both modes, e.g. "#3b82f6"
# : type(map) - per-mode:
# navbar_color:
#   light: "#3b82f6"
#   dark: "#60a5fa"
# navbar_color: null

# Explicit ordering of navbar items by their display text. Items not listed
# are appended after the listed ones, preserving their original order.
# : null - (default) items appear in the order they are added during build
# : type(list) - ordered list of navbar labels, e.g.:
# navbar_order:
#   - User Guide
#   - Reference
#   - Demos
#   - Changelog
# navbar_order: null

# Content-area gradient preset (same preset names as navbar_style); adds a
# subtle radial glow at the top of the content area.
# : type(str) - a preset name (sets `preset`)
# : type(map) - (default) set the fields explicitly, as below
# content_style:
#   preset: null   # null = disabled; else a gradient preset name
#   pages: all     # "all" or "homepage"

# Scale to Fit
# ------------
# Auto-shrink wide HTML output to the content width. The matched element's
# nearest output wrapper is scaled down (never up).
# : null - (default) disabled
# : false - disabled
# : type(list) - CSS selectors to auto-scale, e.g. ["#pb_tbl"]
# Per-page override: `scale-to-fit: ["#pb_tbl"]`
# scale_to_fit: null

# Minimum scale for scale-to-fit; below it, content is shown full size with
# horizontal scrolling instead.
# : null - (default) no minimum
# : false - no minimum
# : type(float) - minimum scale factor, 0-1 (e.g. 0.4 = don't shrink below 40%)
# : mobile - disable scaling at viewports ≤ 576px
# : tablet - disable scaling at viewports ≤ 768px
# : desktop - disable scaling at viewports ≤ 992px
# Per-page override: `scale-to-fit-min-scale: "tablet"`
# scale_to_fit_min_scale: null

# Navigation Icons
# ----------------
# Lucide icons prepended to sidebar/navbar entries.
# : {} - (default) no icons
# : false - disabled
# : type(map) - an icon per navbar/sidebar entry:
# nav_icons:
#   navbar:
#     "User Guide": book-open
#   sidebar:
#     Reference: code
# nav_icons: {}

# UI Features
# -----------
# Keyboard shortcuts and help overlay.
# keyboard_nav: true

# Auto-generated package-info page (dependency details), linked from homepage Meta.
# package_info_page: true

# Back-to-top floating button.
# back_to_top: true

# Footer attribution ("Site created with Great Docs").
# attribution: true

# Custom Head HTML
# ----------------
# Injected into <head> of every page.
# : [] - (default) nothing injected
# : type(str) - inline HTML, e.g. '<link rel="preconnect" href="https://example.com">'
# : type(list) - several entries, mixing inline HTML and `text:`/`file:` maps:
# include_in_header:
#   - '<script defer src="/analytics.js"></script>'
#   - file: partials/head.html
# include_in_header: []

# Freeze (Execution Caching)
# --------------------------
# Whether computational documents re-run during builds. A scalar shorthand
# sets `mode` (e.g. `freeze: false`).
# mode:
#   : auto - (default) re-render only when the source changes
#   : true - never re-render during project render
#   : false - execute every document on every build
#   : null - as false
# pre_render: script(s) to run before render (e.g. copy _freeze/ into the build dir)
# freeze:
#   mode: auto
#   pre_render: []

# Pre-render Scripts
# ------------------
# Quarto's native pre-render hook (alternative to freeze.pre_render). Copied
# into the build directory and wired into _quarto.yml. Paths are relative to
# root.
# : [] - (default) no scripts
# : type(str) - a single script, e.g. scripts/before-render.py
# : type(list) - several, e.g. [scripts/before-render.py, scripts/other.py]
# pre_render: []

# Agent Skills
# ------------
# Emits a SKILL.md conforming to the Agent Skills spec (https://agentskills.io/)
# so coding agents can learn the package.
# skill:
#   enabled: true       # Emit a SKILL.md for this package (default: true)
#   file: null          # Path to a hand-written SKILL.md (overrides auto-generation)
#   well_known: true    # Also serve at /.well-known/agent-skills/{name}/SKILL.md + index.json
#   # Strings for the Gotchas section.
#   gotchas: []
#   # Strings for the Best Practices section.
#   best_practices: []
#   # Manual decision-table rows. Example:
#   #   decision_table:
#   #     - need: "Parse a file"
#   #       use: read_yaml()
#   decision_table: []
#   extra_body: null    # Path to extra Markdown appended to the generated body
#   # Multiple named skills (overrides 'file' when set):
#   # skills:
#   #   - name: my-package
#   #     file: skills/my-package/SKILL.md
#   #   - name: authoring-pages
#   #     file: skills/authoring-pages/SKILL.md
#   skills: []

# Social Cards & Open Graph
# -------------------------
# Auto-generate <meta> tags for social media previews (LinkedIn, Discord, Slack,
# Bluesky, Mastodon, X/Twitter, and other platforms). Enabled by default.
#
# Fine-grained control:
# social_cards:
#   enabled: true
#   image: assets/social-card.png   # Default og:image for all pages
#   twitter_site: "@myhandle"       # Twitter/X site @handle
#   twitter_card: summary_large_image  # "summary" or "summary_large_image"
# social_cards:
#   enabled: true          # Auto-generate social preview meta tags (default: true)
#   image: null            # Default og:image for all pages; omitted from meta tags when null
#   twitter_card: null     # "summary" or "summary_large_image"
#   twitter_site: null     # Twitter/X site @handle (e.g. "@myhandle")

# Page Status Badges
# ------------------
# Lifecycle indicators in sidebar navigation. Pages opt in via frontmatter
# (`status: new`, `deprecated`, ...).
# page_status:
#   enabled: false            # Master switch for page status badges
#   show_in_sidebar: true     # Show badges next to sidebar navigation links
#   show_on_pages: true       # Show a status indicator below page titles (like tags)
#   # Built-in status definitions (extend or override).
#   statuses:
#     new:
#       label: New
#       icon: sparkles
#       color: "#10b981"
#       description: Recently added
#     updated:
#       label: Updated
#       icon: refresh-cw
#       color: "#3b82f6"
#       description: Recently updated
#     beta:
#       label: Beta
#       icon: flask-conical
#       color: "#f59e0b"
#       description: Beta feature
#     deprecated:
#       label: Deprecated
#       icon: triangle-alert
#       color: "#ef4444"
#       description: May be removed in a future release
#     experimental:
#       label: Experimental
#       icon: beaker
#       color: "#8b5cf6"
#       description: API may change without notice
#     upcoming:
#       label: Upcoming
#       icon: rocket
#       color: "#e63946"
#       description: Coming in a future release

# Page Tags
# ---------
# Categorize pages for discoverability via frontmatter
# (`tags: [Python, Testing, API]`).
# tags:
#   enabled: false         # Master switch for page tags
#   index_page: true       # Auto-generate a tags index page listing all tags and their pages
#   show_on_pages: true    # Render tag pills above page titles, linked to the tag index
#   hierarchical: true     # Support hierarchical tags with "/" (e.g. "Python/Testing")
#   # Optional tag icons (tag name -> Lucide icon). Example:
#   #   icons:
#   #     Python: code
#   icons: {}
#   # Shadow tags: names hidden from public view (internal organization only).
#   # Shadow-tagged pages are indexed but their tags are not rendered.
#   shadow: []
#   scoped: false          # Show a tag cloud scoped to the section on section pages
#   location: top          # Default tag pill placement: "top" or "bottom"

# SEO
# ---
# Generates sitemap.xml, robots.txt, and discoverability metadata.
# seo:
#   enabled: true            # Master switch for all SEO features
#   sitemap:
#     enabled: true          # Generate sitemap.xml
#     # Change frequency by page type (always|hourly|daily|weekly|monthly|yearly|never).
#     changefreq:
#       homepage: weekly
#       reference: monthly
#       user_guide: monthly
#       changelog: weekly
#       default: monthly
#     # Priority by page type (0.0-1.0).
#     priority:
#       homepage: 1.0
#       reference: 0.8
#       user_guide: 0.9
#       changelog: 0.6
#       default: 0.5
#   robots:
#     enabled: true          # Generate robots.txt
#     allow_all: true        # Allow all crawlers by default
#     disallow: []           # Paths to disallow, e.g. ["/drafts/", "/_internal/"]
#     crawl_delay: null      # Optional crawl delay in seconds
#     extra_rules: []        # Extra raw lines, e.g. ["User-agent: GPTBot", "Disallow: /"]
#   canonical:
#     enabled: true          # Add canonical URLs to pages
#     # Base URL (e.g. "https://example.github.io/pkg/"); auto-detected from
#     # GitHub Pages when null.
#     base_url: null
#   title_template: "{page_title} | {site_name}"   # supports {page_title} and {site_name}
#   structured_data:
#     enabled: true              # Add JSON-LD to pages
#     type: SoftwareSourceCode   # Schema.org type
#   default_description: null   # Falls back to the package description when null