sphinx-gp-highlighting 0.0.1a33__tar.gz

sphinx_gp_highlighting-0.0.1a33/.gitignore

@@ -0,0 +1,233 @@
+# Node
+node_modules/
+*.tsbuildinfo
+.vitest-cache/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Generated by sphinx_fonts extension (downloaded at build time)
+docs/_static/fonts/
+docs/_static/css/fonts.css
+
+# Claude Code
+**/CLAUDE.local.md
+**/CLAUDE.*.md
+**/.claude/settings.local.json
+
+# Playwright MCP
+.playwright-mcp/
+
+# Repo-local pytest mirror (do not track — validator-only)
+out/
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

sphinx_gp_highlighting-0.0.1a33/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: sphinx-gp-highlighting
+Version: 0.0.1a33
+Summary: Reusable Pygments lexers and inline highlighting for Sphinx
+Project-URL: Repository, https://github.com/git-pull/gp-sphinx
+Author-email: Tony Narlock <tony@git-pull.com>
+License: MIT
+Keywords: documentation,highlighting,pygments,sphinx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: docutils
+Requires-Dist: pygments
+Requires-Dist: sphinx>=8.1
+Description-Content-Type: text/markdown
+
+# sphinx-gp-highlighting
+
+Reusable Sphinx highlighting helpers for git-pull documentation. The package
+ships Pygments lexers for documentation-oriented blocks and Sphinx inline
+literal helpers for commands, paths, and directories.
+
+## Install
+
+```console
+$ pip install sphinx-gp-highlighting
+```
+
+## Usage
+
+Enable the extension in `conf.py`:
+
+```python
+extensions = ["sphinx_gp_highlighting"]
+```
+
+Use the `tree` lexer for directory layouts:
+
+````markdown
+```tree
+python_module
+├── package
+│   └── __init__.py
+└── pyproject.toml
+```
+````

sphinx_gp_highlighting-0.0.1a33/README.md

@@ -0,0 +1,30 @@
+# sphinx-gp-highlighting
+
+Reusable Sphinx highlighting helpers for git-pull documentation. The package
+ships Pygments lexers for documentation-oriented blocks and Sphinx inline
+literal helpers for commands, paths, and directories.
+
+## Install
+
+```console
+$ pip install sphinx-gp-highlighting
+```
+
+## Usage
+
+Enable the extension in `conf.py`:
+
+```python
+extensions = ["sphinx_gp_highlighting"]
+```
+
+Use the `tree` lexer for directory layouts:
+
+````markdown
+```tree
+python_module
+├── package
+│   └── __init__.py
+└── pyproject.toml
+```
+````

sphinx_gp_highlighting-0.0.1a33/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "sphinx-gp-highlighting"
+version = "0.0.1a33"
+description = "Reusable Pygments lexers and inline highlighting for Sphinx"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+  "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["sphinx", "pygments", "highlighting", "documentation"]
+dependencies = [
+  "docutils",
+  "pygments",
+  "sphinx>=8.1",
+]
+
+[project.entry-points."pygments.lexers"]
+"directory-tree" = "sphinx_gp_highlighting.lexers:DirectoryTreeLexer"
+
+[project.urls]
+Repository = "https://github.com/git-pull/gp-sphinx"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_gp_highlighting"]
+
+[tool.gp-sphinx.docs]
+showcase = ["examples"]

sphinx_gp_highlighting-0.0.1a33/src/sphinx_gp_highlighting/__init__.py

@@ -0,0 +1,100 @@
+"""Reusable Sphinx highlighting helpers.
+
+Registers documentation-oriented Pygments lexers and inline literal
+helpers for Sphinx projects.
+
+Examples
+--------
+>>> from sphinx_gp_highlighting import setup
+>>> callable(setup)
+True
+"""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import typing as t
+
+from sphinx.util.logging import getLogger
+
+from sphinx_gp_highlighting.inline import (
+    HighlightingInlineTransform,
+    cmd_role,
+    dir_role,
+    path_role,
+)
+from sphinx_gp_highlighting.lexers import DirectoryTreeLexer
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+_EXTENSION_VERSION = "0.0.1a33"
+_TREE_ALIASES: tuple[str, ...] = ("tree", "directory-tree", "dir-tree")
+
+logger = getLogger(__name__)
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["DirectoryTreeLexer", "HighlightingInlineTransform", "setup"]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Register the package lexers with Sphinx.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance.
+
+    Returns
+    -------
+    ExtensionMetadata
+        Extension metadata with version and parallel-build flags.
+
+    Examples
+    --------
+    >>> from sphinx_gp_highlighting import setup
+    >>> callable(setup)
+    True
+    """
+    for alias in _TREE_ALIASES:
+        app.add_lexer(alias, DirectoryTreeLexer)
+    app.add_config_value(
+        "gp_highlighting_inline_literals",
+        default="off",
+        rebuild="env",
+        types=frozenset({str}),
+        description=(
+            "Inline literal auto-highlighting mode. Use ``'safe'`` to "
+            "highlight configured commands and clear path/directory literals."
+        ),
+    )
+    app.add_config_value(
+        "gp_highlighting_inline_commands",
+        default=[],
+        rebuild="env",
+        types=frozenset({list, tuple}),
+        description=(
+            "Command names eligible for safe inline literal highlighting "
+            "when ``gp_highlighting_inline_literals`` is ``'safe'``."
+        ),
+    )
+    app.add_role("cmd", cmd_role)
+    app.add_role("path", path_role)
+    app.add_role("dir", dir_role)
+    app.add_transform(HighlightingInlineTransform)
+
+    static_dir = str(pathlib.Path(__file__).parent / "_static")
+
+    def _add_static_path(app: Sphinx) -> None:
+        if static_dir not in app.config.html_static_path:
+            app.config.html_static_path.append(static_dir)
+
+    app.connect("builder-inited", _add_static_path)
+    app.add_css_file("css/sphinx_gp_highlighting.css")
+    return {
+        "version": _EXTENSION_VERSION,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_gp_highlighting-0.0.1a33/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css

@@ -0,0 +1,17 @@
+.gp-sphinx-highlighting-inline {
+  white-space: nowrap;
+}
+
+.gp-sphinx-highlighting-inline--kind-command,
+.gp-sphinx-highlighting-inline--kind-shell-session {
+  color: var(--color-code-foreground, inherit);
+}
+
+.gp-sphinx-highlighting-inline--kind-path,
+.gp-sphinx-highlighting-inline--kind-dir {
+  color: var(--color-api-name, inherit);
+}
+
+.gp-sphinx-highlighting-inline--kind-dir::after {
+  color: var(--color-foreground-muted, currentColor);
+}

sphinx_gp_highlighting-0.0.1a33/src/sphinx_gp_highlighting/inline.py

@@ -0,0 +1,350 @@
+"""Inline literal roles and transforms for Sphinx highlighting."""
+
+from __future__ import annotations
+
+import re
+import typing as t
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+if t.TYPE_CHECKING:
+    from docutils.parsers.rst.states import Inliner
+
+InlineLiteralKind: t.TypeAlias = t.Literal["command", "shell-session", "path", "dir"]
+
+_BASE_CLASS = "gp-sphinx-highlighting-inline"
+_COMMAND_LANGUAGE = "bash"
+_SHELL_SESSION_LANGUAGE = "console"
+_SHELL_SESSION_RE = re.compile(r"^\$ \S")
+_HOME_OR_DOT_PATH_RE = re.compile(r"^(?:~|\.{1,2}/)[^\s`]*$")
+_WINDOWS_PATH_RE = re.compile(r"^[A-Za-z]:[\\/][^\s`]+$")
+_RELATIVE_DIR_RE = re.compile(r"^(?:[\w.-]+/)+$")
+_RELATIVE_FILE_RE = re.compile(r"^(?:[\w.-]+/)+[\w.-]+\.[A-Za-z0-9][\w.-]*$")
+_ABSOLUTE_PATH_ROOTS = frozenset(
+    {
+        "Applications",
+        "Library",
+        "Users",
+        "bin",
+        "dev",
+        "etc",
+        "home",
+        "lib",
+        "lib64",
+        "mnt",
+        "opt",
+        "proc",
+        "root",
+        "run",
+        "sbin",
+        "srv",
+        "sys",
+        "tmp",
+        "usr",
+        "var",
+        "Volumes",
+    }
+)
+
+
+def classify_inline_literal(
+    text: str,
+    *,
+    commands: t.Iterable[str] = (),
+) -> InlineLiteralKind | None:
+    """Classify a literal that is safe to highlight automatically.
+
+    Parameters
+    ----------
+    text : str
+        Literal text.
+    commands : iterable of str
+        Command names eligible for bare command highlighting.
+
+    Returns
+    -------
+    InlineLiteralKind | None
+        The safe literal kind, or ``None`` when the text should remain
+        an ordinary inline literal.
+
+    Examples
+    --------
+    >>> classify_inline_literal("tmuxp freeze my-session", commands=["tmuxp"])
+    'command'
+    >>> classify_inline_literal("~/.config/tmuxp/")
+    'dir'
+    >>> classify_inline_literal("module_name") is None
+    True
+    """
+    candidate = text.strip()
+    if not candidate or "\n" in candidate:
+        return None
+    if _SHELL_SESSION_RE.match(candidate):
+        return "shell-session"
+    first_word = candidate.split(maxsplit=1)[0]
+    if first_word in set(commands) and " " in candidate:
+        return "command"
+    if _is_path_like(candidate):
+        return "dir" if candidate.endswith("/") else "path"
+    return None
+
+
+def build_highlighted_literal(text: str, kind: InlineLiteralKind) -> nodes.literal:
+    """Build a literal node with package highlighting classes.
+
+    Parameters
+    ----------
+    text : str
+        Literal text.
+    kind : InlineLiteralKind
+        Highlighting kind.
+
+    Returns
+    -------
+    nodes.literal
+        Literal node ready for the Sphinx HTML writer.
+
+    Examples
+    --------
+    >>> node = build_highlighted_literal("tmuxp freeze my-session", "command")
+    >>> node["language"]
+    'bash'
+    >>> "gp-sphinx-highlighting-inline--kind-command" in node["classes"]
+    True
+    >>> "language" in build_highlighted_literal("~/.config/tmuxp/", "dir")
+    False
+    """
+    node = nodes.literal(
+        text,
+        text,
+        classes=[_BASE_CLASS, f"{_BASE_CLASS}--kind-{kind}"],
+    )
+    if kind in {"command", "shell-session"}:
+        node["classes"].extend(["code", "highlight"])
+        node["language"] = (
+            _SHELL_SESSION_LANGUAGE if kind == "shell-session" else _COMMAND_LANGUAGE
+        )
+    return node
+
+
+def cmd_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline shell commands.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = cmd_role(
+    ...     "cmd", "{cmd}`tmuxp freeze x`", "tmuxp freeze x", 1, None
+    ... )
+    >>> messages
+    []
+    >>> nodes_[0]["language"]
+    'bash'
+    """
+    return [build_highlighted_literal(text, "command")], []
+
+
+def path_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline filesystem paths.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = path_role("path", "{path}`~/x.py`", "~/x.py", 1, None)
+    >>> messages
+    []
+    >>> "gp-sphinx-highlighting-inline--kind-path" in nodes_[0]["classes"]
+    True
+    """
+    return [build_highlighted_literal(text, "path")], []
+
+
+def dir_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline filesystem directories.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = dir_role("dir", "{dir}`~/x/`", "~/x/", 1, None)
+    >>> messages
+    []
+    >>> "gp-sphinx-highlighting-inline--kind-dir" in nodes_[0]["classes"]
+    True
+    """
+    return [build_highlighted_literal(text, "dir")], []
+
+
+class HighlightingInlineTransform(Transform):
+    """Highlight safe inline literals when configured."""
+
+    default_priority = 120
+
+    def apply(self) -> None:
+        """Rewrite safe inline literals to highlighted literal nodes."""
+        env = getattr(self.document.settings, "env", None)
+        if env is None:
+            return
+        config = env.app.config
+        if getattr(config, "gp_highlighting_inline_literals", "off") != "safe":
+            return
+        commands = tuple(getattr(config, "gp_highlighting_inline_commands", ()))
+        for literal in list(self.document.findall(nodes.literal)):
+            if _should_skip_literal(literal):
+                continue
+            kind = classify_inline_literal(literal.astext(), commands=commands)
+            if kind is None:
+                continue
+            replacement = build_highlighted_literal(literal.astext(), kind)
+            replacement.source = literal.source
+            replacement.line = literal.line
+            literal.replace_self(replacement)
+
+
+def _is_path_like(text: str) -> bool:
+    """Return whether ``text`` looks like a filesystem path.
+
+    Examples
+    --------
+    >>> _is_path_like("~/.config/tmuxp/")
+    True
+    >>> _is_path_like("/mnt/c/Users/example")
+    True
+    >>> _is_path_like("application/json")
+    False
+    """
+    return bool(
+        _HOME_OR_DOT_PATH_RE.match(text)
+        or _WINDOWS_PATH_RE.match(text)
+        or _is_absolute_filesystem_path(text)
+        or _is_relative_filesystem_path(text)
+    )
+
+
+def _is_absolute_filesystem_path(text: str) -> bool:
+    """Return whether ``text`` starts with a common absolute path root.
+
+    Examples
+    --------
+    >>> _is_absolute_filesystem_path("/proc/version")
+    True
+    >>> _is_absolute_filesystem_path("/api/pull")
+    False
+    """
+    if not text.startswith("/"):
+        return False
+    first_component = text.removeprefix("/").split("/", maxsplit=1)[0]
+    return first_component in _ABSOLUTE_PATH_ROOTS
+
+
+def _is_relative_filesystem_path(text: str) -> bool:
+    """Return whether ``text`` is a conservative bare relative path.
+
+    Examples
+    --------
+    >>> _is_relative_filesystem_path("docs/conf.py")
+    True
+    >>> _is_relative_filesystem_path("resources/read")
+    False
+    """
+    if text.startswith(("/", "~", "./", "../")):
+        return False
+    first_component = text.split("/", maxsplit=1)[0]
+    if "." in first_component and not first_component.startswith("."):
+        return False
+    return bool(_RELATIVE_DIR_RE.match(text) or _RELATIVE_FILE_RE.match(text))
+
+
+def _should_skip_literal(node: nodes.literal) -> bool:
+    """Return whether a literal should not be rewritten."""
+    classes: set[str] = set(node.get("classes", ()))
+    if _BASE_CLASS in classes:
+        return True
+    return bool("language" in node or "code" in classes)

sphinx_gp_highlighting-0.0.1a33/src/sphinx_gp_highlighting/lexers.py

@@ -0,0 +1,82 @@
+"""Pygments lexers for documentation-focused code blocks."""
+
+from __future__ import annotations
+
+import re
+import typing as t
+
+from pygments.lexer import RegexLexer
+from pygments.token import Comment, Name, Punctuation, Text, Whitespace
+
+
+class DirectoryTreeLexer(RegexLexer):
+    r"""Lexer for ``tree(1)``-style directory listings.
+
+    The lexer targets documentation snippets that show project layouts
+    with box-drawing connectors. It deliberately uses standard Pygments
+    token types so existing Sphinx styles can colour the output without
+    package-specific token CSS.
+
+    Examples
+    --------
+    >>> from pygments.token import Token
+    >>> lexer = DirectoryTreeLexer()
+    >>> source = '''\
+    ... root
+    ... └── pyproject.toml  # config
+    ... '''
+    >>> tokens = list(lexer.get_tokens(source))
+    >>> (Token.Punctuation, '└──') in tokens
+    True
+    >>> (Token.Name, 'pyproject.toml') in tokens
+    True
+    >>> (Token.Comment.Single, '# config') in tokens
+    True
+    """
+
+    name = "Directory tree"
+    aliases = ["tree", "directory-tree", "dir-tree"]  # noqa: RUF012
+    filenames: t.ClassVar[list[str]] = []
+    mimetypes = ["text/x-directory-tree"]  # noqa: RUF012
+
+    tokens = {  # noqa: RUF012
+        "root": [
+            (r"\n", Whitespace),
+            (r"[ \t]+", Whitespace),
+            (r"(?:├──|└──|│)", Punctuation),
+            (r"#.*$", Comment.Single),
+            (r"[^/\s#]+/", Name.Namespace),
+            (r"[^/\s#.]+\.[^/\s#]+", Name),
+            (r"[^/\s#]+", Name.Namespace),
+            (r".", Text),
+        ],
+    }
+
+    @staticmethod
+    def analyse_text(text: str) -> float:
+        r"""Return a confidence score for tree-like text.
+
+        Parameters
+        ----------
+        text : str
+            Source text to inspect.
+
+        Returns
+        -------
+        float
+            ``0.7`` when box-drawing tree connectors are present,
+            otherwise ``0.0``.
+
+        Examples
+        --------
+        >>> DirectoryTreeLexer.analyse_text('''\
+        ... root
+        ... └── pyproject.toml
+        ... ''')
+        0.7
+        >>> DirectoryTreeLexer.analyse_text("plain text")
+        0.0
+        """
+        if re.search(r"(?m)^[│ \t]*(?:├──|└──)\s+\S", text):
+            return 0.7
+        return 0.0

sphinx_gp_highlighting-0.0.1a33/src/sphinx_gp_highlighting/py.typed

@@ -0,0 +1 @@
+