Module

docs.collection

Docs collection — load, index, and query documentation pages.

DocsCollectionis the central data structure. It loads markdown files from disk, renders them once viaMarkdownRenderer, and stores frozenDocPageinstances in memory. After construction the collection is immutable and thread-safe.

Usage::

from chirp.docs import DocsCollection

collection = DocsCollection.load(Path("content/docs"))
page = collection.get("getting-started")
1Class

Classes

DocsCollection 11 ▼
Immutable collection of documentation pages. Constructed via the ``load()`` class method which eag…

Immutable collection of documentation pages.

Constructed via theload()class method which eagerly reads and renders all markdown files at startup. After construction every public method is a pure read — no I/O, no locks.

Design decisions:

* **Eager load** — all content rendered at startup so request-
  time cost is a dict lookup + template render.  For 100 docs
  at ~50 KB each this is ~5 MB of memory, well within budget.
* **Single directory** — constructor takes one ``Path``.
  Multiple directories can be merged via ``merge()``.
* **Keyword search** — simple ranked keyword matching over
  title + raw markdown.  No external dependencies.  Can be
  upgraded to trigram/BM25 later without API change.

Methods

load 2 DocsCollection ▼
Walk *content_dir*, parse and render every ``.md`` file.
classmethod
def load(cls, content_dir: Path, *, include_drafts: bool = False) -> DocsCollection
Parameters
Name Type Description
content_dir —

Directory containing markdown files (searched recursively).
include_drafts —

IfFalse (default), pages with draft: truein frontmatter are excluded.

Default:False
Returns
DocsCollection An immutable ``DocsCollection`` ready for querying.
get 1 DocPage | None ▼
Look up a page by slug. Returns ``None`` if not found.
def get(self, slug: str) -> DocPage | None
Parameters
Name Type Description
slug —
Returns
DocPage | None
get_block 2 DocBlock | None ▼
Look up a single section block on a page. Returns ``None`` if the page or the …
def get_block(self, slug: str, block_id: str) -> DocBlock | None

Look up a single section block on a page.

ReturnsNoneif the page or the block id is unknown. Block ids are the snake_case identifiers assigned by_split_blocks (seechirp.docs.frontmatter).

Parameters
Name Type Description
slug —
block_id —
Returns
DocBlock | None
list 1 tuple[DocPage, ...] ▼
Return pages sorted by (order, title).
def list(self, *, category: str | None = None) -> tuple[DocPage, ...]
Parameters
Name Type Description
category —

If provided, only return pages in this category.

Default:None
Returns
tuple[DocPage, ...]
search 1 tuple[DocPage, ...] ▼
Keyword search over title and raw markdown content. Returns pages ranked by re…
def search(self, query: str) -> tuple[DocPage, ...]

Keyword search over title and raw markdown content.

Returns pages ranked by relevance (title matches weighted higher). Empty query returns an empty tuple.

Parameters
Name Type Description
query —
Returns
tuple[DocPage, ...]
categories 0 tuple[str, ...] ▼
Return distinct category names, sorted alphabetically.
def categories(self) -> tuple[str, ...]
Returns
tuple[str, ...]
as_nav 0 tuple[NavGroup, ...] ▼
Return navigation groups for sidebar rendering.
def as_nav(self) -> tuple[NavGroup, ...]
Returns
tuple[NavGroup, ...]
merge 1 DocsCollection ▼
Combine two collections into one (e.g. markdown + autodoc). Duplicate slugs in…
def merge(self, other: DocsCollection) -> DocsCollection

Combine two collections into one (e.g. markdown + autodoc).

Duplicate slugs in other overwrite pages from self.

Parameters
Name Type Description
other —
Returns
DocsCollection
Internal Methods 3 ▼
__init__ 1 ▼
def __init__(self, pages: tuple[DocPage, ...]) -> None
Parameters
Name Type Description
pages —
__len__ 0 int ▼
def __len__(self) -> int
Returns
int
__contains__ 1 bool ▼
def __contains__(self, slug: str) -> bool
Parameters
Name Type Description
slug —
Returns
bool