plesty.sdk.commands.docs.picker
===============================

.. py:module:: plesty.sdk.commands.docs.picker

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   plesty.sdk.commands.docs.picker.PICKER_ASSETS
   plesty.sdk.commands.docs.picker.PICKER_MARKER
   plesty.sdk.commands.docs.picker.SIDEBAR_MARKER


Functions
---------

.. autoapisummary::

   plesty.sdk.commands.docs.picker._reference_tags
   plesty.sdk.commands.docs.picker.carries_picker
   plesty.sdk.commands.docs.picker.stamp_release_tree
   plesty.sdk.commands.docs.picker.stamp_release_trees


Module Contents
---------------

.. py:data:: PICKER_ASSETS
   :value: ('plesty-versions.js', 'plesty-versions.css')


.. py:data:: PICKER_MARKER
   :value: 'plesty-versions.js'


.. py:data:: SIDEBAR_MARKER
   :value: 'wy-side-nav-search'


.. py:function:: _reference_tags(prefix: str, version_tag: str) -> str

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

   :param prefix: Relative path from the page to its tree root ("" or "../"…).
   :param version_tag: The release the tree holds, marked current in the picker.

   :returns: The markup to insert before the page's ``</head>``.


.. py:function:: 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.

   :param tree: Directory holding the built release.

   :returns: True when the release's landing page references the picker.


.. py:function:: 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.

   :param tree: Directory holding the built release, e.g. ``html/releases/0.3``.
   :param version_tag: The release the tree holds, in 'major.minor' format.

   :returns: The number of pages stamped.


.. py:function:: stamp_release_trees(releases_dir: str, release_pattern: re.Pattern[str]) -> dict[str, int]

   Add the picker to every published release that lacks it.

   :param releases_dir: The directory holding one subdirectory per release.
   :param release_pattern: Matches the directory names that are releases.

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