Reference

sphinx_gp_highlighting/__init__.py.

Registered surface

Copyable config snippet

extensions = [
    "sphinx_gp_highlighting",
]

Lexers

sphinx-gp-highlighting registers these Pygments aliases:

Alias	Purpose
tree	Preferred directory-tree fence name
directory-tree	Explicit directory-tree alias
dir-tree	Short directory-tree alias

Config values

gp_highlighting_inline_literals

config env

config env

gp_highlighting_inline_literals

Inline literal auto-highlighting mode. Use 'safe' to highlight configured commands and clear path/directory literals.

Type:

str

Default:

'off'

Registered by:

sphinx_gp_highlighting.setup()

gp_highlighting_inline_commands

config env

config env

gp_highlighting_inline_commands

Command names eligible for safe inline literal highlighting when gp_highlighting_inline_literals is 'safe'.

Type:

list | tuple

Default:

[]

Registered by:

sphinx_gp_highlighting.setup()

Roles

:cmd:

role

role

:cmd:

Role for inline shell commands.

Python path:

sphinx_gp_highlighting.inline.cmd_role

class:

class_option

:path:

role

role

:path:

Role for inline filesystem paths.

Python path:

sphinx_gp_highlighting.inline.path_role

class:

class_option

:dir:

role

role

:dir:

Role for inline filesystem directories.

Python path:

sphinx_gp_highlighting.inline.dir_role

class:

class_option

API

sphinx_gp_highlighting.setup(app)

function

function

sphinx_gp_highlighting.setup(app)

Register the package lexers with Sphinx.

Parameters:

app (Sphinx) – Sphinx application instance.

Returns:

Extension metadata with version and parallel-build flags.

Return type:

ExtensionMetadata

Examples

>>> from sphinx_gp_highlighting import setup
>>> callable(setup)
True

class sphinx_gp_highlighting.lexers.DirectoryTreeLexer

class

class

class sphinx_gp_highlighting.lexers.DirectoryTreeLexer

Bases: RegexLexer

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'

attribute

attribute

name = 'Directory tree'

Full name of the lexer, in human-readable form

aliases = ['tree', 'directory-tree', 'dir-tree']

attribute

attribute

aliases = ['tree', 'directory-tree', 'dir-tree']

A list of short, unique identifiers that can be used to look up the lexer from a list, e.g., using get_lexer_by_name().

filenames: ClassVar[list[str]] = []

attribute

attribute

filenames: ClassVar[list[str]] = []

A list of fnmatch patterns that match filenames which contain content for this lexer. The patterns in this list should be unique among all lexers.

mimetypes = ['text/x-directory-tree']

attribute

attribute

mimetypes = ['text/x-directory-tree']

A list of MIME types for content that can be lexed with this lexer.

tokens = <...truncated, 284 chars>

attribute

attribute

tokens = <...truncated, 284 chars>

At all time there is a stack of states. Initially, the stack contains a single state ‘root’. The top of the stack is called “the current state”.

Dict of {'state': [(regex, tokentype, new_state), ...], ...}

new_state can be omitted to signify no state transition. If new_state is a string, it is pushed on the stack. This ensure the new current state is new_state. If new_state is a tuple of strings, all of those strings are pushed on the stack and the current state will be the last element of the list. new_state can also be combined('state1', 'state2', ...) to signify a new, anonymous state combined from the rules of two or more existing ones. Furthermore, it can be ‘#pop’ to signify going back one step in the state stack, or ‘#push’ to push the current state on the stack again. Note that if you push while in a combined state, the combined state itself is pushed, and not only the state in which the rule is defined.

The tuple can also be replaced with include('state'), in which case the rules from the state named by the string are included in the current one.

static analyse_text(text)

staticmethod method

staticmethod method

static analyse_text(text)

Return a confidence score for tree-like text.

Parameters:

text (str) – Source text to inspect.

Returns:

0.7 when box-drawing tree connectors are present, otherwise 0.0.

Return type:

float

Examples

>>> DirectoryTreeLexer.analyse_text('''\
... root
... └── pyproject.toml
... ''')
0.7
>>> DirectoryTreeLexer.analyse_text("plain text")
0.0

sphinx_gp_highlighting.inline.classify_inline_literal(text, *, commands=())

function

function

sphinx_gp_highlighting.inline.classify_inline_literal(text, *, commands=())

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:

The safe literal kind, or None when the text should remain an ordinary inline literal.

Return type:

InlineLiteralKind | None

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

sphinx_gp_highlighting.inline.build_highlighted_literal(text, kind)

function

function

sphinx_gp_highlighting.inline.build_highlighted_literal(text, kind)

Build a literal node with package highlighting classes.

Parameters:

• text (str) – Literal text.

• kind (InlineLiteralKind) – Highlighting kind.

Returns:

Literal node ready for the Sphinx HTML writer.

Return type:

nodes.literal

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