On this page

Guidedog / Documentation 0.2.0

Declaring object types

A project may need names that the standard domains do not know. Declare those object types in TOML. Guidedog can then create targets, index entries, and roles without loading a Python extension. The declaration states a syntax, not executable behavior.

Targets: add_crossref_type

[[crossref_types]]
directive = "setting"
role = "setting"
index = "pair: %s; setting"

.. setting:: DEBUG then makes a target with the id setting-DEBUG and an index entry, and :setting:`DEBUG` links to it, as in Sphinx. index is Sphinx’s indextemplate: its type (single, pair, triple, see, seealso) before the first colon, and the entry after it, with %s the name.

Descriptions: add_object_type

[[object_types]]
directive = "django-admin"
role = "djadmin"
index = "pair: %s; django-admin command"
name = "first-word"
display = "django-admin %s"
program = true

.. django-admin:: migrate [app_label] then describes the command like any object: a signature, content, an id (django-admin-migrate), and an index entry. In Sphinx a parse_node function may read the signature; its usual work is set by fields instead:

name

"whole" (the default): the object’s name is its whole signature. "first-word": the name is the signature up to its first space (pdb’s b(reak) [lineno] is named b(reak)).

display

How the signature is shown, %s standing for it. By default, as written.

program

true: the name becomes the program that options described after it belong to, as .. program:: makes it.

Other names for directives

An extension may register one of Sphinx’s own directives under another name:

[directive_aliases]
django-admin-option = "option"
awaitablefunction = "py:function"

A target without a domain is a standard directive, or one of the default domain’s; a target such as py:function names its domain.

Migrating

guidedog migrate finds each extension conf.py lists that is a module of the project, reads its add_crossref_type, add_object_type, and add_directive calls without running them, and writes these tables. It reports what it cannot declare: a parse_node function (set name, display, and program to match it) and directives, roles, and event handlers written in Python.