Guidedog / Documentación 0.2.0

Referencia de configuración¶

Cada proyecto se configura con conf.toml en su raíz. Guidedog lo lee como datos TOML declarativos, sin ejecutar código arbitrario.

Muchas claves corresponden a variables de conf.py de Sphinx, lo que facilita migrar con guidedog migrate conf.py.

Configuración mínima¶

Basta con los metadatos básicos. Las claves omitidas usan los valores predeterminados:

project = "Field Notes"
author = "Your Name"
version = "1.0"
release = "1.0.0"
language = "en"
root_doc = "index"
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
html_static_path = ["_static"]
pdf_paper_size = "a4"

Metadatos del proyecto¶

Tabla 8 Opciones de metadatos¶
Clave	Tipo	Valor predeterminado	Descripción
`project`	cadena	`"Python"`	Nombre legible del proyecto.
`author`	cadena	`""`	Nombre del autor o de la organización.
`copyright`	cadena	`""`	Aviso de derechos de autor del pie de página.
`version`	cadena	`""`	Versión breve, por ejemplo `"1.0"`.
`release`	cadena	`""`	Versión completa con identificadores alpha o beta, como `"1.0.0b1"`.
`language`	cadena	`"en"`	Código ISO de idioma para composición, separación silábica y traducción, como `"de"` o `"zh_CN"`.
`today`	cadena	`""`	Texto de fecha personalizado; si se omite, la fecha actual se formatea con `today_fmt`.
`today_fmt`	cadena	`""`	Cadena de formato para las fechas.

Opciones generales¶

Tabla 9 Opciones de detección y análisis¶
Clave	Tipo	Valor predeterminado	Descripción
`root_doc`	cadena	`"index"`	Documento que sirve de índice raíz.
`source_suffix`	lista	`[".rst"]`	Extensiones reconocidas como fuentes de documentación.
`exclude_patterns`	lista	`[]`	Patrones glob de archivos y directorios excluidos de la búsqueda de fuentes.
`include_roots`	lista	`[]`	Directorios externos permitidos para incluir fuentes.
`templates_path`	lista	`[]`	Directorios de plantillas HTML y PDF, consultados antes que las plantillas internas.
`extensions`	lista	`[]`	Extensiones de Sphinx implementadas internamente que se activarán, como `"sphinx.ext.autodoc"`.
`primary_domain`	cadena	`"py"`	Dominio predeterminado de directivas y roles sin prefijo, como `"py"`, `"c"` u `"odin"`.
`highlight_language`	cadena	`"default"`	Idioma de los bloques de código cuando no se especifica.
`pygments_style`	cadena	`""`	Estilo Pygments de resaltado para el tema claro.
`pygments_dark_style`	cadena	`""`	Estilo de resaltado para el tema oscuro.
`smartquotes`	booleano	`true`	Convierte comillas rectas y guiones en signos tipográficos.
`rst_prolog`	cadena	`""`	Fragmento reStructuredText añadido al principio de cada documento.
`rst_epilog`	cadena	`""`	Fragmento reStructuredText añadido al final de cada documento.

Numeración y matemáticas¶

Tabla 10 Opciones de numeración¶
Clave	Tipo	Valor predeterminado	Descripción
`numfig`	booleano	`false`	Numera automáticamente figuras, tablas y bloques de código.
`numfig_secnum_depth`	entero	`1`	Profundidad de títulos incluida en los números; `1` produce, por ejemplo, `Fig. 2.1`.
`numfig_format`	tabla	véase más abajo	Formatos de prefijo para `"figure"`, `"table"` y `"code-block"`.
`math_number_all`	booleano	`false`	Numera automáticamente todas las ecuaciones en bloque.
`math_eqref_format`	cadena	`"({number})"`	Formato de las referencias a ecuaciones con `:eq:`.
`mathjax_path`	cadena	URL	URL de CDN o ruta local del paquete JavaScript de MathJax.

Valores predeterminados de numfig_format:

[numfig_format]
figure = "Fig. %s"
table = "Table %s"
code-block = "Listing %s"
section = "Section %s"

Diagnósticos y comprobaciones estrictas¶

Tabla 11 Opciones de diagnóstico¶
Clave	Tipo	Valor predeterminado	Descripción
`nitpicky`	booleano	`false`	Advierte de referencias sin resolver y destinos rotos.
`nitpick_ignore`	lista	`[]`	Lista de pares `[type, target]` exentos de las advertencias estrictas.
`suppress_warnings`	lista	`[]`	Códigos de categorías de advertencia que se omiten.
`keep_warnings`	booleano	`false`	Incluye las advertencias en los documentos publicados.

Opciones de salida HTML¶

Tabla 12 Opciones HTML¶
Clave	Tipo	Valor predeterminado	Descripción
`html_theme`	cadena	`"guidedog"`	Tema usado para generar HTML.
`html_theme_options`	tabla	`{}`	Opciones de clave y valor del tema HTML.
`html_title`	cadena	calculado	Título mostrado en la pestaña del navegador.
`html_short_title`	cadena	calculado	Título breve para las rutas de navegación.
`html_logo`	cadena	`""`	Ruta del logotipo relativa al directorio de fuentes.
`html_favicon`	cadena	`""`	Ruta del favicon.
`html_static_path`	lista	`[]`	Directorios copiados al `_static/` de salida.
`html_extra_path`	lista	`[]`	Directorios copiados a la raíz de salida sin transformación.
`html_css_files`	lista	`[]`	Nombres de archivos CSS adicionales cargados en las páginas HTML.
`html_js_files`	lista	`[]`	Nombres de archivos JavaScript adicionales cargados en las páginas HTML.
`html_permalinks`	booleano	`true`	Añade enlaces permanentes a párrafos y secciones.
`html_permalinks_icon`	cadena	`"¶"`	Símbolo o texto de los enlaces permanentes.
`html_baseurl`	cadena	`""`	URL base canónica para los mapas del sitio y los metadatos.
`html_context`	tabla	`{}`	Diccionario de variables adicionales para las plantillas Jinja.
`html_additional_pages`	tabla	`{}`	Páginas adicionales: `{ "page_name" = "template.html" }`.

Opciones de PDF y Typst¶

Tabla 13 Opciones PDF¶
Clave	Tipo	Valor predeterminado	Descripción
`pdf_paper_size`	cadena	`"a4"`	Formato de papel: `"a4"` o `"us-letter"`.
`pdf_logo`	cadena	`""`	Ruta del logotipo de la cubierta.
`pdf_toplevel_sectioning`	cadena	`"chapter"`	Nivel de división del libro: `"chapter"` o `"part"`.
`pdf_show_urls`	cadena	`"no"`	Visualización de URL en papel: `"no"`, `"inline"` o `"footnote"`.
`pdf_preamble`	cadena	`""`	Código Typst sin procesar insertado en la cabecera del documento.
`pdf_font_paths`	lista	`[]`	Directorios adicionales para buscar fuentes OTF/TTF.
`pdf_packages`	cadena	`"download"`	Política de resolución de paquetes: `"download"` u `"offline"`.
`typst`	cadena	`"typst"`	Nombre o ruta absoluta del ejecutable Typst.

Definir libros PDF¶

La tabla [[pdf_documents]] define uno o más libros del proyecto:

[[pdf_documents]]
root = "index"
file = "guide.pdf"
title = "Field Notes Complete Guide"
author = "Author Name"

[[pdf_documents]]
root = "reference/index"
file = "reference.pdf"
title = "Field Notes Reference"
author = "Author Name"

Opciones de MyST Markdown¶

Tabla 14 Opciones de MyST Markdown¶
Clave	Tipo	Valor predeterminado	Descripción
`myst_enable_extensions`	lista	`["dollarmath"]`	Extensiones de sintaxis: `"colon_fence"`, `"deflist"`, `"dollarmath"`, `"fieldlist"`, `"tasklist"`, `"substitution"`.
`myst_heading_anchors`	entero	`0`	Profundidad de títulos con anclas automáticas; `0` las desactiva.
`myst_substitutions`	tabla	`{}`	Sustituciones de variables de Markdown: `{key = "value"}`.
`myst_url_schemes`	lista	`["http", ...]`	Esquemas URI reconocidos como enlaces externos.
`myst_commonmark_only`	booleano	`false`	Limita el análisis a CommonMark, sin extensiones MyST.

Opciones de Intersphinx¶

extensions = ["sphinx.ext.intersphinx"]
intersphinx_cache_limit = 5
intersphinx_timeout = 30

[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]

Consulte Enlazar con otros proyectos para el procedimiento completo.

Opciones de autodoc para Python¶

Tabla 15 Opciones de autodoc¶
Clave	Tipo	Valor predeterminado	Descripción
`autodoc_source_paths`	lista	`[]`	Directorios de búsqueda de módulos Python para el análisis estático.
`autoclass_content`	cadena	`"class"`	Origen del docstring de clase: `"class"`, `"init"` o `"both"`.
`autodoc_member_order`	cadena	`"alphabetical"`	Orden de miembros: `"alphabetical"`, `"bysource"` o `"groupwise"`.
`autodoc_typehints`	cadena	`"signature"`	Ubicación de anotaciones de tipos: `"signature"`, `"description"` o `"none"`.
`autodoc_default_options`	tabla	`{}`	Opciones predeterminadas de todas las directivas `auto*`.

Consulte Documentar Python con autodoc para las reglas completas de detección.

Opciones de documentación API de Odin¶

Tabla 16 Opciones del dominio Odin¶
Clave	Tipo	Valor predeterminado	Descripción
`odin_autoapi_dirs`	lista	`[]`	Directorios de fuentes donde se buscan paquetes Odin.
`odin_autoapi_root`	cadena	`"api"`	Subdirectorio de salida de la documentación API de Odin.
`odin_autoapi_options`	lista	`["members", "undoc-members"]`	Filtros de los miembros que se incluyen.
`odin_autoapi_member_order`	cadena	`"source"`	Orden de miembros: `"source"` o `"alphabetical"`.

Consulte Documentar Odin para el uso completo del dominio Odin.

Opciones de internacionalización¶

Tabla 17 Opciones i18n¶
Clave	Tipo	Valor predeterminado	Descripción
`locale_dirs`	lista	`["locales"]`	Directorios de búsqueda de catálogos gettext.
`gettext_compact`	booleano	`true`	Agrupa los mensajes de cada directorio en un catálogo.
`gettext_uuid`	booleano	`false`	Añade UUID estables a los mensajes POT.
`gettext_auto_build`	booleano	`true`	Compila los archivos `.po` en catálogos binarios `.mo` durante la compilación.
`figure_language_filename`	cadena	`"{root}.{language}{ext}"`	Plantilla de nombres para seleccionar imágenes localizadas.

Consulte Internacionalización para traducir la documentación.