Sphinx collection engine#

_sphinx_collection is the shared support library behind collection-style Sphinx directives. It owns domain-agnostic filtering, sorting, grouping, bounded YAML loading, browser metadata, result/status controls and generated collection assets.

It is not a standalone Sphinx extension: there is no package-level setup(app) entry point to add to extensions. Use a consuming extension such as Sphinx Gallery Grid or Sphinx YouTube Gallery.

Why it exists#

Keeping collection behavior in one package prevents gallery-grid and typed adapters from drifting on search/filter/sort behavior. The intended ownership is:

  • a domain adapter normalizes records;

  • gallery-grid owns card/layout rendering;

  • _sphinx_collection owns selection and browser-control behavior.

This means a YouTube-specific module should not implement a second search UI, and the leaf video player should never paginate gallery cards.

Programmatic use#

The package lazily exposes selection and grouping helpers such as parse_filter, parse_sort, apply_selection and group_records. It also exposes the shared asset/integrity hooks used by consuming Sphinx extensions.

The package initializer intentionally avoids eager imports so data-only helpers remain usable in code paths that do not have Sphinx/docutils installed.

Bounded YAML contract#

The shared YAML loader uses yaml.safe_load and deterministic resource limits. Current limits are:

Resource

Limit

Input bytes

8 MiB

YAML aliases

100

Nesting depth

32

Expanded values

100,000

Scalar characters

1,048,576

Collection items

5,000

Recursive aliases and inputs that exceed a bound raise BoundedYAMLError. These limits exist because safe YAML object construction alone does not prevent resource-exhaustion input.

Generated browser assets#

Consuming extensions register a digest of the shared CSS/JavaScript as an HTML rebuild dependency. The assets are written atomically and verified again at build-finished. Searchable gallery output is also checked for the expected document-owned status marker so a mixed old/new incremental build fails instead of publishing a structurally inconsistent UI.

Progressive enhancement#

The static collection remains readable without JavaScript. Browser controls may hide, reorder or add local cards after load, but they do not own the canonical build-time record set.