Preview gp-sphinx#36 curated default-value rendering

.github/workflows/docs.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - master
+      # [DO NOT MERGE] preview branch for gp-sphinx PR #36 — revert before merge.
+      - improved-defaults-reprs
 
 permissions:
   contents: read
@@ -49,6 +51,21 @@ jobs:
         if: env.PUBLISH == 'true'
         run: uv python install ${{ matrix.python-version }}
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        if: env.PUBLISH == 'true'
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        if: env.PUBLISH == 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies [w/ docs]
         if: env.PUBLISH == 'true'
         run: uv sync --all-extras --dev

.github/workflows/tests.yml

@@ -33,6 +33,19 @@ jobs:
           print("libtmux Server:", server)
           '
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
@@ -111,6 +124,19 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies
         run: uv sync --all-extras --dev
 

pyproject.toml

@@ -106,6 +106,16 @@ libtmux = "libtmux.pytest_plugin"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.uv.sources]
+# TEMPORARY: pull gp-sphinx-family deps from the improved-defaults-reprs
+# branch on git-pull/gp-sphinx so this PR previews the curated-default
+# rendering work before a release bump propagates the changes via PyPI.
+# Revert this block when gp-sphinx>=0.0.1a18 lands.
+gp-sphinx = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/gp-sphinx" }
+sphinx-autodoc-typehints-gp = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-typehints-gp" }
+sphinx-autodoc-api-style = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-api-style" }
+sphinx-autodoc-pytest-fixtures = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-pytest-fixtures" }
+
 [tool.uv.exclude-newer-package]
 # git-pull packages release in lockstep with their workspaces, so a
 # fresh release blocking on the 3-day cooldown blocks every

src/libtmux/constants.py

@@ -54,11 +54,25 @@ class PaneDirection(enum.Enum):
 
 
 class _DefaultOptionScope:
-    # Sentinel value for default scope
-    ...
+    """Sentinel type for the ``scope=`` parameter's default value.
+
+    The lone instance :data:`DEFAULT_OPTION_SCOPE` is used as the
+    default for option-related helpers; receiving methods use ``is``
+    comparison against the sentinel to detect "no explicit scope was
+    passed" and infer the right scope from the bound object type.
+    """
 
 
 DEFAULT_OPTION_SCOPE: _DefaultOptionScope = _DefaultOptionScope()
+"""Sentinel default for ``scope=`` parameters on option / hook helpers.
+
+When ``scope is DEFAULT_OPTION_SCOPE`` the caller hasn't selected an
+explicit :class:`OptionScope`; the receiving method
+(:meth:`Pane._show_option`, :meth:`Server.show_options`, etc.)
+infers the appropriate scope from the bound object type
+(``Pane`` → ``OptionScope.Pane``, ``Server`` → ``OptionScope.Server``,
+…).
+"""
 
 
 class OptionScope(enum.Enum):