sphinx_packaging.tconf

The tconf directive and role for configuration fields in pyproject.toml etc.

Classes:

TConfXRefRole([fix_parens, lowercase, ...])	Customised XRef role for tconf roles.
TOMLConf(name, arguments, options, content, ...)	The tconf directive.

Functions:

resolve_xref(app, env, node, contnode)	Resolve as-yet-unresolved XRefs for tconf roles.
setup(app)	Setup sphinx_packaging.tconf.

class TConfXRefRole(fix_parens=False, lowercase=False, nodeclass=None, innernodeclass=None, warn_dangling=False)

Bases: XRefRole

Customised XRef role for tconf roles.

Methods:

process_link(env, refnode, ...)

Construct a link from the parsed content of the role.

process_link(env, refnode, has_explicit_title, title, target)

Construct a link from the parsed content of the role.

Parameters:

• env (BuildEnvironment) – The Sphinx build environment.

• refnode (Element) – The reference node.

• has_explicit_title (bool) – Whether the role has an explicit title.

• title (str) – The title of the XRef role.

• target (str) – The target of the XRef role. (:tconf:`title <target>`)

Return type:

Tuple[str, str]

Returns:

A tuple of (title, target).

class TOMLConf(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: GenericObject

The tconf directive.

Methods:

format_default(default)	Formats the :default: option.
format_required(required)	Formats the :required: option.
format_type(the_type)	Formats the :type: option.
handle_signature(sig, signode)	Parse the signature of the tconf directive.
run()	Process the content of the directive.

Attributes:

indextemplate

The template string for index entries.

static format_default(default)

Formats the :default: option.

Parameters:

default (str)

Return type:

str

static format_required(required)

Formats the :required: option.

Parameters:

required (str)

Return type:

bool

static format_type(the_type)

Formats the :type: option.

Parameters:

the_type (str)

Return type:

str

handle_signature(sig, signode)

Parse the signature of the tconf directive.

Parameters:

• sig (str) – The name of the field.

• signode (desc_signature) – The signature node created by Sphinx.

Return type:

str

Returns:

The final component of the field path (e.g. foo.bar -> bar).

indextemplate = 'pair: %s; TOML configuration field'

Type:    str

The template string for index entries.

option_spec = {'default': <function unchanged_required>, 'noindex': <function _flag>, 'required': <function unchanged_required>, 'type': <function unchanged_required>}

Type:    Mapping[str, Callable[[str], Any]]

run()

Process the content of the directive.

Return type:

List[Node]

resolve_xref(app, env, node, contnode)

Resolve as-yet-unresolved XRefs for tconf roles.

Parameters:

• app (Sphinx) – The Sphinx application.

• env (BuildEnvironment) – The Sphinx build environment.

• node (Node) – The cross reference node which has not yet been.

• contnode (Node) – The child node of the reference node, which provides the formatted text.

Return type:

Optional[reference]

setup(app)

Setup sphinx_packaging.tconf.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

Dict[str, Any]