En esta página

Guidedog / Documentación 0.2.0

Declarar tipos de objetos

Un proyecto puede necesitar nombres ajenos a los dominios estándar. Declare sus tipos de objetos en TOML para crear destinos, entradas de índice y roles sin cargar Python. La declaración expresa sintaxis, no comportamiento ejecutable.

Destinos: add_crossref_type

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

.. setting:: DEBUG crea un destino con ID setting-DEBUG y una entrada de índice; :setting:`DEBUG` enlaza a él, como en Sphinx. index es el indextemplate de Sphinx: el tipo (single, pair, triple, see, seealso) precede al primer signo de dos puntos y después va la entrada, con %s para el nombre.

Descripciones: 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] describe el comando como cualquier objeto: firma, contenido, ID (django-admin-migrate) y entrada de índice. En Sphinx una función parse_node puede interpretar la firma; aquí su trabajo habitual se define mediante campos:

name

"whole" (predeterminado): el nombre es la firma completa. "first-word": es el texto hasta el primer espacio; por ejemplo, b(reak) [lineno] de pdb se llama b(reak).

display

Cómo se muestra la firma, representada por %s. Por defecto se conserva tal cual.

program

true: el nombre pasa a ser el programa al que pertenecen las opciones siguientes, como con .. program::.

Otros nombres para las directivas

Una extensión puede registrar una directiva de Sphinx con otro nombre:

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

Un destino sin dominio es una directiva estándar o del dominio predeterminado; uno como py:function indica su dominio.

Migración

guidedog migrate encuentra las extensiones de conf.py que son módulos del proyecto. Lee sin ejecutarlas sus llamadas a add_crossref_type, add_object_type y add_directive y escribe las tablas. Informa de lo que no puede declarar: funciones parse_node (ajuste name, display y program) y directivas, roles y manejadores de eventos escritos en Python.