Sphinxcontrib-DomainTools API refeerence#

This Sphinx extension provides a tool for easy sphinx domain creation.

Installation#

pip install sphinxcontrib-domaintools

Usage#

In this example there is created a simple domain for GNU Make:

from sphinxcontrib.domaintools import custom_domain

def setup(app):
    app.add_domain(custom_domain('GnuMakeDomain',
        name  = 'make',
        label = "GNU Make",

        elements = dict(
            target = dict(
                objname      = "Make Target",
                indextemplate = "pair: %s; Make Target",
            ),
            var   = dict(
                objname = "Make Variable",
                indextemplate = "pair: %s; Make Variable"
            ),
        )))

Complete example you find in sphinxcontrib-makedomain package.

A more complex example you can find in sphinxcontrib-cmakedomain package.

Reference#

custom_domain(class_name, name='', label='', elements = {}):

Create a custom domain.

For each given element there are created a directive and a role for referencing and indexing.

Parameters:

  • class_name – ClassName of your new domain (e.g. GnuMakeDomain)

  • name – short name of your domain (part of directives, e.g. make)

  • label – Long name of your domain (e.g. GNU Make)

  • elements –

    dictionary of your domain directives/roles

    An element value is a dictionary with following possible entries:

    • objname - Long name of the entry, defaults to entry’s key

    • role - role name, defaults to entry’s key

    • indextemplate - e.g. pair: %s; Make Target, where %s will be the matched part of your role. You may leave this empty, defaults to pair: %s; <objname>

    • parse_node - a function with signature (env, sig, signode), defaults to None.

    • fields - A list of fields where parsed fields are mapped to. this is passed to Domain as doc_field_types parameter.

    • ref_nodeclass - class passed as XRefRole’s innernodeclass, defaults to None.

Fields API Reference#

Utility code for “Doc fields”.

“Doc fields” are reST field lists in object descriptions that will be domain-specifically transformed to a more appealing presentation.

class sphinx.util.docfields.DocFieldTransformer(directive: ObjectDescription)#

Transforms field lists in “doc field” syntax into better-looking equivalents, using the field type definitions given on a domain.

transform(node: field_list) → None#

Transform a single field list node.

transform_all(node: desc_content) → None#

Transform all field list children of a node.

typemap: dict[str, tuple[Field, bool]]#
class sphinx.util.docfields.Field(name: str, names: tuple[str, ...] = (), label: str = '', has_arg: bool = True, rolename: str = '', bodyrolename: str = '')#

A doc field that is never grouped. It can have an argument or not, the argument can be linked using a specified rolename. Field should be used for doc fields that usually don’t occur more than once.

The body can be linked using a specified bodyrolename if the content is just a single inline or text node.

Example:

:returns: description of the return value
:rtype: description of the return type
is_grouped = False#
is_typed = False#
make_entry(fieldarg: str, content: list[Node]) → tuple[str, list[Node]]#
make_field(types: dict[str, list[Node]], domain: str, item: tuple, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Element | None = None) → nodes.field#
make_xref(rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = <class 'sphinx.addnodes.literal_emphasis'>, contnode: Node | None = None, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Element | None = None) → Node#
make_xrefs(rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = <class 'sphinx.addnodes.literal_emphasis'>, contnode: Node | None = None, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Element | None = None) → list[Node]#
class sphinx.util.docfields.GroupedField(name: str, names: tuple[str, ...] = (), label: str = '', rolename: str = '', can_collapse: bool = False)#

A doc field that is grouped; i.e., all fields of that type will be transformed into one field with its body being a bulleted list. It always has an argument. The argument can be linked using the given rolename. GroupedField should be used for doc fields that can occur more than once. If can_collapse is true, this field will revert to a Field if only used once.

Example:

:raises ErrorClass: description when it is raised
is_grouped = True#
list_type#

alias of bullet_list

make_field(types: dict[str, list[Node]], domain: str, items: tuple, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Element | None = None) → nodes.field#
class sphinx.util.docfields.TypedField(name: str, names: tuple[str, ...] = (), typenames: tuple[str, ...] = (), label: str = '', rolename: str = '', typerolename: str = '', can_collapse: bool = False)#

A doc field that is grouped and has type information for the arguments. It always has an argument. The argument can be linked using the given rolename, the type using the given typerolename.

Two uses are possible: either parameter and type description are given separately, using a field from names and one from typenames, respectively, or both are given using a field from names, see the example.

Example:

:param foo: description of parameter foo
:type foo:  SomeClass

-- or --

:param SomeClass foo: description of parameter foo
is_typed = True#
make_field(types: dict[str, list[Node]], domain: str, items: tuple, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Element | None = None) → nodes.field#

License#

New BSD License.

Author#

Kay-Uwe (Kiwi) Lorenz (http://quelltexter.org)