plesty.sdk.commands.docs.picker

Stamping the version picker into release docs built before it existed.

A release tree is built once, from the tag, and never rebuilt. The releases already published therefore carry no picker, and a reader who switched to one had no way back — the picker was a one-way trip out of the current docs.

Sphinx cannot help here: these trees are finished artifacts. So the two assets the picker needs are copied in beside the ones already there, and the two tags that reference them are inserted into every page. Nothing else is touched — the prose, the API reference and the existing stylesheets of a historical release stay exactly as they were built.

Attributes

PICKER_ASSETS
PICKER_MARKER
SIDEBAR_MARKER

Functions

_reference_tags(→ str)	Return the stylesheet and script tags pointing at the stamped assets.
carries_picker(→ bool)	Return whether a built release tree can offer the version picker.
stamp_release_tree(→ int)	Add the picker to one already-built release tree.
stamp_release_trees(→ dict[str, int])	Add the picker to every published release that lacks it.

Module Contents

plesty.sdk.commands.docs.picker.PICKER_ASSETS = ('plesty-versions.js', 'plesty-versions.css')

plesty.sdk.commands.docs.picker.PICKER_MARKER = 'plesty-versions.js'

plesty.sdk.commands.docs.picker.SIDEBAR_MARKER = 'wy-side-nav-search'

plesty.sdk.commands.docs.picker._reference_tags(prefix: str, version_tag: str) → str

Return the stylesheet and script tags pointing at the stamped assets.

Parameters:

• prefix (str) – Relative path from the page to its tree root (”” or “../”…).

• version_tag (str) – The release the tree holds, marked current in the picker.

Returns:

The markup to insert before the page’s </head>.

Return type:

str

plesty.sdk.commands.docs.picker.carries_picker(tree: str) → bool

Return whether a built release tree can offer the version picker.

True once its landing page references the picker — either because Sphinx built it that way or because stamp_release_tree added it. False for a release built before the Read-the-Docs theme, which has no sidebar to mount on and can never be given one short of a rebuild from the tag.

The manifest uses this to decide what to advertise: offering a version whose pages have no picker strands the reader there.

Parameters:

tree (str) – Directory holding the built release.

Returns:

True when the release’s landing page references the picker.

Return type:

bool

plesty.sdk.commands.docs.picker.stamp_release_tree(tree: str, version_tag: str) → int

Add the picker to one already-built release tree.

Idempotent: a page that already references the picker is left untouched, so re-running over a stamped tree — every deploy does — changes nothing.

Parameters:

• tree (str) – Directory holding the built release, e.g. html/releases/0.3.

• version_tag (str) – The release the tree holds, in ‘major.minor’ format.

Returns:

The number of pages stamped.

Return type:

int

plesty.sdk.commands.docs.picker.stamp_release_trees(releases_dir: str, release_pattern: re.Pattern[str]) → dict[str, int]

Add the picker to every published release that lacks it.

Parameters:

• releases_dir (str) – The directory holding one subdirectory per release.

• release_pattern (re.Pattern[str]) – Matches the directory names that are releases.

Returns:

Pages stamped per release tag, omitting releases that needed nothing.

Return type:

dict[str, int]