gp-sphinx 0.0.1a16.dev4__tar.gz → 0.0.1a18.dev0__tar.gz

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gp-sphinx
-Version: 0.0.1a16.dev4
+Version: 0.0.1a18.dev0
 Summary: Shared Sphinx documentation platform for git-pull projects
 Project-URL: Bug Tracker, https://github.com/git-pull/gp-sphinx/issues
 Project-URL: Documentation, https://gp-sphinx.git-pull.com
@@ -27,18 +27,18 @@ Requires-Dist: docutils
 Requires-Dist: gp-libs
 Requires-Dist: linkify-it-py
 Requires-Dist: myst-parser
-Requires-Dist: sphinx-autodoc-typehints-gp==0.0.1a16.dev4
+Requires-Dist: sphinx-autodoc-typehints-gp==0.0.1a18.dev0
 Requires-Dist: sphinx-copybutton
 Requires-Dist: sphinx-design
-Requires-Dist: sphinx-fonts==0.0.1a16.dev4
-Requires-Dist: sphinx-gp-opengraph==0.0.1a16.dev4
-Requires-Dist: sphinx-gp-sitemap==0.0.1a16.dev4
-Requires-Dist: sphinx-gp-theme==0.0.1a16.dev4
+Requires-Dist: sphinx-fonts==0.0.1a18.dev0
+Requires-Dist: sphinx-gp-opengraph==0.0.1a18.dev0
+Requires-Dist: sphinx-gp-sitemap==0.0.1a18.dev0
+Requires-Dist: sphinx-gp-theme==0.0.1a18.dev0
 Requires-Dist: sphinx-inline-tabs
 Requires-Dist: sphinx<9,>=8.1
 Requires-Dist: sphinxext-rediraffe
 Provides-Extra: argparse
-Requires-Dist: sphinx-autodoc-argparse==0.0.1a16.dev4; extra == 'argparse'
+Requires-Dist: sphinx-autodoc-argparse==0.0.1a18.dev0; extra == 'argparse'
 Description-Content-Type: text/markdown
 
 # gp-sphinx &middot; [![Python Package](https://img.shields.io/pypi/v/gp-sphinx.svg)](https://pypi.org/project/gp-sphinx/) [![License](https://img.shields.io/github/license/git-pull/gp-sphinx.svg)](https://github.com/git-pull/gp-sphinx/blob/main/LICENSE)

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gp-sphinx"
-version = "0.0.1a16.dev4"
+version = "0.0.1a18.dev0"
 description = "Shared Sphinx documentation platform for git-pull projects"
 requires-python = ">=3.10,<4.0"
 authors = [
@@ -26,15 +26,15 @@ readme = "README.md"
 keywords = ["sphinx", "documentation", "configuration"]
 dependencies = [
   "sphinx>=8.1,<9",
-  "sphinx-gp-theme==0.0.1a16.dev4",
-  "sphinx-fonts==0.0.1a16.dev4",
+  "sphinx-gp-theme==0.0.1a18.dev0",
+  "sphinx-fonts==0.0.1a18.dev0",
   "myst-parser",
   "docutils",
-  "sphinx-autodoc-typehints-gp==0.0.1a16.dev4",
+  "sphinx-autodoc-typehints-gp==0.0.1a18.dev0",
   "sphinx-inline-tabs",
   "sphinx-copybutton",
-  "sphinx-gp-opengraph==0.0.1a16.dev4",
-  "sphinx-gp-sitemap==0.0.1a16.dev4",
+  "sphinx-gp-opengraph==0.0.1a18.dev0",
+  "sphinx-gp-sitemap==0.0.1a18.dev0",
   "sphinxext-rediraffe",
   "sphinx-design",
   "linkify-it-py",
@@ -43,7 +43,7 @@ dependencies = [
 
 [project.optional-dependencies]
 argparse = [
-  "sphinx-autodoc-argparse==0.0.1a16.dev4",
+  "sphinx-autodoc-argparse==0.0.1a18.dev0",
 ]
 
 [project.urls]

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/src/gp_sphinx/__init__.py

@@ -7,7 +7,7 @@ import logging
 __title__ = "gp-sphinx"
 __package_name__ = "gp_sphinx"
 __description__ = "Shared Sphinx documentation platform for git-pull projects"
-__version__ = "0.0.1a16.dev4"
+__version__ = "0.0.1a18.dev0"
 __author__ = "Tony Narlock"
 __github__ = "https://github.com/git-pull/gp-sphinx"
 __docs__ = "https://gp-sphinx.git-pull.com"

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/src/gp_sphinx/config.py

@@ -32,6 +32,7 @@ import json
 import logging
 import os.path
 import pathlib
+import sys
 import typing as t
 
 from gp_sphinx.defaults import (
@@ -39,6 +40,7 @@ from gp_sphinx.defaults import (
     DEFAULT_AUTODOC_CLASS_SIGNATURE,
     DEFAULT_AUTODOC_MEMBER_ORDER,
     DEFAULT_AUTODOC_OPTIONS,
+    DEFAULT_AUTODOC_PRESERVE_DEFAULTS,
     DEFAULT_AUTODOC_TYPEHINTS,
     DEFAULT_COPYBUTTON_LINE_CONTINUATION_CHARACTER,
     DEFAULT_COPYBUTTON_PROMPT_IS_REGEXP,
@@ -206,6 +208,108 @@ def make_linkcode_resolve(
     return linkcode_resolve
 
 
+def make_workspace_linkcode_resolve(
+    *,
+    repo_root: pathlib.Path | str,
+    github_url: str,
+    source_branch: str = "main",
+) -> Callable[[str, dict[str, str]], str | None]:
+    """Create a ``linkcode_resolve`` function for a uv/pnpm workspace monorepo.
+
+    Unlike :func:`make_linkcode_resolve`, which assumes a single-package layout
+    rooted at ``<repo>/<src_dir>/<package>/…``, this resolver computes URLs by
+    taking the absolute path returned by :func:`inspect.getsourcefile` and
+    making it relative to *repo_root*. This works uniformly across all packages
+    in a workspace layout such as ``<repo>/packages/<pkg>/src/<module>/…``
+    without requiring per-package registration.
+
+    The URL always points to *source_branch* — there is no per-package version
+    tag branching because each workspace package carries its own independent
+    version string while the docs site tracks the live monorepo tip.
+
+    Returns ``None`` when the domain is not ``"py"``, the module is not
+    imported, the attribute cannot be resolved, ``inspect.getsourcefile``
+    returns a falsy value, or the source file lives outside *repo_root*.
+
+    Parameters
+    ----------
+    repo_root : pathlib.Path or str
+        Absolute path to the repository root (the directory that contains
+        ``pyproject.toml`` and the ``packages/`` tree).
+    github_url : str
+        Base GitHub repository URL, e.g.
+        ``"https://github.com/git-pull/gp-sphinx"``.
+    source_branch : str
+        Branch used in all generated URLs (default ``"main"``).
+
+    Returns
+    -------
+    Callable[[str, dict[str, str]], str | None]
+        A function suitable for ``linkcode_resolve`` in a Sphinx config.
+
+    Examples
+    --------
+    >>> import pathlib
+    >>> resolver = make_workspace_linkcode_resolve(
+    ...     repo_root=pathlib.Path("/tmp/repo"),
+    ...     github_url="https://github.com/git-pull/gp-sphinx",
+    ... )
+    >>> callable(resolver)
+    True
+    >>> resolver("c", {"module": "x", "fullname": "y"}) is None
+    True
+    """
+    root = pathlib.Path(repo_root).resolve()
+
+    def linkcode_resolve(domain: str, info: dict[str, str]) -> str | None:
+        if domain != "py":
+            return None
+
+        modname = info["module"]
+        fullname = info["fullname"]
+
+        submod = sys.modules.get(modname)
+        if submod is None:
+            return None
+
+        obj: object = submod
+        for part in fullname.split("."):
+            try:
+                obj = getattr(obj, part)
+            except Exception:  # noqa: PERF203
+                return None
+
+        try:
+            unwrap = inspect.unwrap
+        except AttributeError:
+            pass
+        else:
+            if callable(obj):
+                obj = unwrap(obj)
+
+        try:
+            fn = inspect.getsourcefile(obj)  # type: ignore[arg-type]
+        except Exception:
+            fn = None
+        if not fn:
+            return None
+
+        try:
+            source, lineno = inspect.getsourcelines(obj)  # type: ignore[arg-type]
+        except Exception:
+            lineno = None
+
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}" if lineno else ""
+
+        rel = os.path.relpath(fn, start=root)
+        if rel.startswith(".."):
+            return None
+
+        return f"{github_url}/blob/{source_branch}/{rel}{linespec}"
+
+    return linkcode_resolve
+
+
 def merge_sphinx_config(
     *,
     project: str,
@@ -442,6 +546,7 @@ def merge_sphinx_config(
         "autodoc_member_order": DEFAULT_AUTODOC_MEMBER_ORDER,
         "autodoc_class_signature": DEFAULT_AUTODOC_CLASS_SIGNATURE,
         "autodoc_typehints": DEFAULT_AUTODOC_TYPEHINTS,
+        "autodoc_preserve_defaults": DEFAULT_AUTODOC_PRESERVE_DEFAULTS,
         "toc_object_entries_show_parents": DEFAULT_TOC_OBJECT_ENTRIES_SHOW_PARENTS,
         "autodoc_default_options": dict(DEFAULT_AUTODOC_OPTIONS),
         # Copybutton

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/src/gp_sphinx/defaults.py

@@ -232,15 +232,32 @@ Examples
 
 DEFAULT_SPHINX_FONT_PRELOAD: list[tuple[str, int, str]] = [
     ("IBM Plex Sans", 400, "normal"),
+    ("IBM Plex Sans", 500, "normal"),
+    ("IBM Plex Sans", 600, "normal"),
     ("IBM Plex Sans", 700, "normal"),
+    ("IBM Plex Sans", 400, "italic"),
     ("IBM Plex Mono", 400, "normal"),
+    ("IBM Plex Mono", 700, "normal"),
 ]
 """Font preload hints for critical rendering path.
 
+Each entry is ``(family, weight, style)``. Faces in this list are
+emitted as ``<link rel="preload" as="font">`` tags so the browser
+fetches them in parallel with the critical CSS/HTML, before
+``font-display: block`` would otherwise hide text waiting on a
+lazy ``@font-face`` request.
+
+The list covers every face Furo / ``furo-tw.css`` is observed to
+demand above the fold: body (Sans 400), headings + sidebar labels
+(Sans 500), epigraph blockquotes (Sans 600), strong / current
+sidebar (Sans 700), inline ``<em>`` and announcement-bar emphasis
+(Sans 400 italic), code blocks (Mono 400), and bold inline code
+``<strong><code>`` (Mono 700).
+
 Examples
 --------
 >>> len(DEFAULT_SPHINX_FONT_PRELOAD)
-3
+7
 """
 
 DEFAULT_SPHINX_FONT_FALLBACKS: list[dict[str, str]] = [
@@ -346,6 +363,29 @@ Examples
 'description'
 """
 
+DEFAULT_AUTODOC_PRESERVE_DEFAULTS: bool = True
+"""Preserve source text of parameter defaults instead of ``repr()``.
+
+When ``True``, Sphinx's ``update_default_value`` listener wraps each
+``inspect.Parameter.default`` in a ``DefaultValue`` shim whose
+``__repr__`` returns the *literal source text* of the default
+expression. The result is that signatures render
+``scope=DEFAULT_OPTION_SCOPE`` instead of
+``scope=<libtmux.constants._DefaultOptionScope object>`` and
+``retry_exceptions=(libtmux_exc.LibTmuxException,)`` instead of
+``(<class 'libtmux.exc.LibTmuxException'>,)``.
+
+The flag has no effect on synthetic ``__init__`` (dataclass / attrs /
+NamedTuple) where ``inspect.getsource()`` returns nothing — Sphinx's
+listener bails out for those, leaving the defaults as ``=<factory>``
+until a sibling listener handles them.
+
+Examples
+--------
+>>> DEFAULT_AUTODOC_PRESERVE_DEFAULTS
+True
+"""
+
 DEFAULT_COPYBUTTON_LINE_CONTINUATION_CHARACTER: str = "\\"
 """Line continuation character for sphinx-copybutton."""
 

{gp_sphinx-0.0.1a16.dev4 → gp_sphinx-0.0.1a18.dev0}/src/gp_sphinx/myst_lexer.py

@@ -30,7 +30,7 @@ from __future__ import annotations
 import typing as t
 
 from pygments.lexers.markup import MarkdownLexer, RstLexer
-from pygments.token import String, Whitespace
+from pygments.token import Name, String, Text, Whitespace
 
 if t.TYPE_CHECKING:
     import re
@@ -60,7 +60,15 @@ class MystLexer(MarkdownLexer):
     >>> tokens = [(str(tok), v) for tok, v in lexer.get_tokens("Hello")]
     >>> any(v == "Hello" for _, v in tokens)
     True
-    """
+
+    Triple-colon fences (MyST ``colon_fence`` extension) tokenize the
+    opening, option keys, and closing markers so source samples
+    documenting MyST directives render with proper highlighting:
+
+    >>> tokens = tokenize_myst(":::{note}\\nhi\\n:::\\n")
+    >>> any(":::{note}" == v for _, v in tokens)
+    True
+    """  # noqa: D301 - backslashes are in doctest code, not escape sequences
 
     name = "MyST Markdown"
     aliases: t.ClassVar[list[str]] = ["myst", "myst-md"]
@@ -124,6 +132,97 @@ class MystLexer(MarkdownLexer):
 
         yield match.start("closing"), String.Backtick, match.group("closing")
 
+    def _handle_colon_fence(
+        self,
+        match: re.Match[str],
+    ) -> t.Iterator[tuple[int, _TokenType, str]]:
+        """Lex a ``:::{<directive>}`` colon-fenced block (MyST ``colon_fence``).
+
+        Emits the opening ``:::{name}`` line and the closing ``:::`` line
+        as ``String.Backtick`` (matching how :meth:`_handle_eval_rst`
+        renders fence boundaries). Within the body, lines matching the
+        ``:<key>: <value>`` MyST option syntax tokenize the key as
+        ``Name.Tag`` (RST-style option-list convention) and the value as
+        ``Text``; remaining body content is ``Text``.
+
+        Parameters
+        ----------
+        match : re.Match[str]
+            Regex match with named groups ``opening``, ``newline``,
+            ``body``, and ``closing``.
+
+        Yields
+        ------
+        tuple[int, _TokenType, str]
+            ``(offset, token_type, value)`` triples whose offsets are
+            relative to the start of the full document, suitable for
+            ``get_tokens_unprocessed``.
+
+        Notes
+        -----
+        Handles exactly three colons (``:::``). Four-or-more-colon
+        variants (``::::{name}``) are a known MyST feature but are not
+        currently in scope; if they appear later, capture the opening
+        colon count and require the closing count to match via a
+        backreference.
+
+        Body content is emitted as plain ``Text`` (plus ``Name.Tag`` for
+        option keys). MyST directive bodies vary by directive — e.g.
+        ``:::{grid}`` carries sphinx-design markup, ``:::{tab-set}``
+        carries inline content — so a single inner-language delegation
+        is not appropriate. Specialized inner highlighting can be added
+        per directive in a follow-up.
+
+        Examples
+        --------
+        >>> tokens = tokenize_myst(
+        ...     ":::{auto-pytest-plugin} my_project.pp\\n"
+        ...     ":package: my-project\\n"
+        ...     ":::\\n"
+        ... )
+        >>> any(":::{auto-pytest-plugin}" in v for _, v in tokens)
+        True
+        >>> any("Name.Tag" in tok and v == ":package:" for tok, v in tokens)
+        True
+        """  # noqa: D301 - backslashes are in doctest code, not escape sequences
+        import re as _re
+
+        yield match.start("opening"), String.Backtick, match.group("opening")
+        yield match.start("newline"), Whitespace, match.group("newline")
+
+        body = match.group("body")
+        body_offset = match.start("body")
+        # Walk the body line-by-line. Lines matching ``:<key>:[ <value>]``
+        # tokenize the key as Name.Tag; everything else is Text.
+        # Pattern: leading ``:``, identifier, trailing ``:``, then
+        # optional whitespace + value through end of line.
+        option_re = _re.compile(r"^(:[\w\-]+:)([^\n]*)(\n)", _re.MULTILINE)
+        cursor = 0
+        for option_match in option_re.finditer(body):
+            # Emit any text between the previous match end and this
+            # match's start as plain Text.
+            if option_match.start() > cursor:
+                preceding = body[cursor : option_match.start()]
+                yield body_offset + cursor, Text, preceding
+            yield (
+                body_offset + option_match.start(1),
+                Name.Tag,
+                option_match.group(1),
+            )
+            value = option_match.group(2)
+            if value:
+                yield body_offset + option_match.start(2), Text, value
+            yield (
+                body_offset + option_match.start(3),
+                Whitespace,
+                option_match.group(3),
+            )
+            cursor = option_match.end()
+        if cursor < len(body):
+            yield body_offset + cursor, Text, body[cursor:]
+
+        yield match.start("closing"), String.Backtick, match.group("closing")
+
     # tokens must be declared AFTER _handle_eval_rst because the class
     # body is executed sequentially and the dict literal references
     # _handle_eval_rst by name.
@@ -150,6 +249,27 @@ class MystLexer(MarkdownLexer):
                 ),
                 _handle_eval_rst,
             ),
+            # Triple-colon fence (MyST colon_fence extension):
+            # :::{<directive>}[ <info-string>] ... :::
+            #
+            # The MarkdownLexer parent has no rule for these so they
+            # fall through to plain Token.Text without this handler.
+            # Handles exactly three colons; four-or-more variants are
+            # out of scope (see _handle_colon_fence Notes).
+            (
+                (
+                    # group opening: ::: fence + braced directive name +
+                    # optional info string (e.g. :::{tab-set} centered)
+                    r"(?P<opening>^:::\{[\w\-]+\}[^\n]*)"
+                    r"(?P<newline>\n)"
+                    # group body: directive content, non-greedy to stop
+                    # at the first closing fence
+                    r"(?P<body>(?:.|\n)*?)"
+                    # group closing: bare ::: at start of line
+                    r"(?P<closing>^:::[ \t]*$\n?)"
+                ),
+                _handle_colon_fence,
+            ),
             # All MarkdownLexer root rules follow unchanged, providing
             # highlighting for normal fenced code blocks, inline code,
             # headings, etc.