Compatibilidad con Sphinx¶
Guidedog sigue a Sphinx donde eso facilita migrar un proyecto y mide la compatibilidad función por función. No ejecuta configuración Python ni extensiones Python arbitrarias. Un build correcto demuestra que se ha construido el proyecto, no una equivalencia completa.
Proyectos y publicación¶
| Operación | Comportamiento implementado |
|---|---|
| Estructura del proyecto y opciones de compilación | Directorios de fuentes y salida al estilo de Sphinx; -a -E -W -n -D -t -j -b -M -c -C. |
| Configuración | Datos TOML con los nombres habituales de Sphinx. La migración convierte literales e informa de valores calculados. |
| Generadores de HTML | html, dirhtml y singlehtml. Los anclajes de la página única incluyen los nombres de los documentos. |
| Otros generadores | text, gettext y dummy. pdf utiliza Typst; latex y latexpdf eligen esa misma ruta. |
| Plantillas | Implementación propia de Jinja, html_context con tipos, herencia de diseños y páginas adicionales. |
| Compilación incremental | Los cambios en fuentes, dependencias, plantillas, configuración y búsquedas de referencias invalidan la salida afectada. |
| Publicación | Una generación completa. Si falla la compilación, se conserva la generación publicada anterior. |
-D acepta true y false, o 1 y 0, para booleanos. Si existe contents pero no index, puede usarse como raíz, con una advertencia. Las páginas adicionales de plantillas se guardan como archivos en la raíz del sitio, incluso con dirhtml. El contrato exacto está en Plantillas.
Una página sin cambios vuelve a emitir sus diagnósticos. Así, -W significa lo mismo en una compilación limpia y en otra sin cambios. Al borrar un documento, se elimina su página. La publicación usa un diario recuperable; el siguiente build resuelve un commit interrumpido. Véanse el invariante y los límites de plataforma en Publicar una generación completa.
No están disponibles los generadores epub, man, texinfo, linkcheck, doctest, coverage y changes. Sus nombres reciben un mensaje de corrección. tools/linkcheck es una herramienta independiente de verificación del repositorio.
Lenguajes de origen¶
| Lector | Pruebas y límites |
|---|---|
| reStructuredText | 98 fuentes del corpus coinciden con los árboles e identificadores de Docutils comparados. La comparación excluye las posiciones en el código y varios atributos internos de gestión. |
| CommonMark 0.31.2 | Pasan los 652 ejemplos de la especificación. |
| MyST 0.16.1 reference | Coinciden 215 de 218 casos del lector y 8 de 10 compilaciones de prueba de Sphinx. Las diferencias restantes están documentadas. |
Estas pruebas usan versiones fijadas y no implican compatibilidad con todas las versiones posteriores. Ejecute guidedog formats para ver los resultados de lectores y renderizadores del ejecutable. Los directorios de los lectores contienen sus notas de conformidad.
rst_prolog sigue a los campos bibliográficos iniciales y rst_epilog al código fuente. Ninguno se inserta en Markdown. only e ifconfig conservan sus secciones cuando se cumple la condición. Su ubicación puede diferir de Sphinx si una sección condicional cambia el nivel de las secciones vecinas. Los títulos de sección dentro de eval-rst de MyST son errores.
Referencias y dominios¶
Guidedog implementa toctrees, etiquetas, glosarios, numeración de secciones y figuras, y referencias ref, doc, numref, term, download, any, keyword, option, envvar y token. Los objetos pueden aparecer en toctrees, barras laterales y esquemas de página.
Están implementados los dominios estándar, Python, C, C++, JavaScript, reStructuredText y matemáticas. El dominio Odin es una extensión propia de Guidedog. Describe paquetes, declaraciones, firmas y páginas de API generadas. Véanse su descubrimiento basado solo en fuentes y sus límites en Documentar Odin.
Los campos de parámetros, retorno, excepciones y variables forman descripciones estructuradas. Los nombres canónicos actúan como alias en referencias e inventarios. Los valores predeterminados y anotaciones de Python conservan la escritura original; Sphinx puede reimprimirlos con el unparser de Python. Las declaraciones C++ publican versiones de identificadores e inventarios de símbolos compatibles con Sphinx. Se aplican límites de anidación. Los paréntesis anidados se analizan en tiempo lineal.
numref sustituye un único espacio de número e informa si el destino no está numerado. Las secciones se numeran en orden de lectura. Un documento se numera una sola vez; una segunda toctree numerada informa del conflicto. Los detalles de sustitución e identificadores están en las pruebas de referencias.
El índice general, el índice de módulos y la búsqueda están integrados. La búsqueda compara prefijos de palabras; no reproduce la reducción a raíces del inglés de Sphinx.
Los tipos de objetos declarativos sustituyen una clase útil de registros de extensiones Python. object_types, crossref_types y directive_aliases describen sus datos. Un parse_node personalizado de Python se convierte en reglas declarativas de nombre, presentación y programa. La migración informa del código que no puede expresar. Véase Declarar tipos de objetos.
Comportamiento de las extensiones integradas¶
| Comportamiento | Estado |
|---|---|
todo, ifconfig, extlinks, autosectionlabel |
Integradas. Para enlaces extlinks escritos directamente puede sugerirse un rol. |
graphviz |
La biblioteca Graphviz enlazada produce dibujos estáticos. Se aplica el confinamiento de recursos. |
intersphinx |
Inventarios locales y descargados. Windows solo admite archivos locales por ahora. |
githubpages |
Archivos de publicación integrados para un sitio estático. |
mathjax e imgmath |
Las fórmulas HTML usan MathJax. Para PDF se traduce a Typst el subconjunto de LaTeX admitido. |
myst_parser |
La capa de Markdown implementada para proyectos. |
Directivas doctest |
Se muestran. El generador del proyecto no ejecuta sus pruebas. |
autodoc |
Se lee el código fuente Python sin importar ni ejecutar el paquete. |
El autodoc basado en fuentes no puede descubrir todos los objetos creados en ejecución. Los módulos compilados, decoradores externos, valores calculados y manejadores de eventos tienen límites explícitos. Python 3.13 y las pruebas fijadas de los documentadores de Sphinx sirven de referencia. Véanse todas las opciones y excepciones en Documentar Python con autodoc.
autosummary, napoleon, viewcode y las extensiones Python arbitrarias quedan fuera de esta ruta. Se informa de las extensiones no admitidas en la configuración y de las directivas o roles desconocidos en su ubicación de origen. Debe revisarse el contenido omitido antes de publicar. Se aceptan otros nombres de tema, pero se usa la implementación de Guidedog.
Confianza y límites de recursos¶
Una compilación normal acepta HTML y Typst sin procesar, plantillas e inventarios de red del proyecto. La lectura local se limita al directorio de fuentes y a las raíces compartidas explícitamente. Un enlace simbólico no amplía ese límite. Plantillas, archivos estáticos, includes, imágenes, fuentes y código de API siguen la misma regla.
Las imágenes de Graphviz se resuelven respecto al documento y quedan confinadas. Los datos de imagen admitidos se incrustan en el dibujo. imagepath y fontpath no amplían el límite. Typst se ejecuta con una raíz privada que contiene los directorios legibles y mantiene las plantillas y preámbulos dentro de los recursos declarados.
--untrusted reduce el límite de lectura al directorio de fuentes. Omite contenido sin procesar, URL inseguras, recursos externos, plantillas Typst del proyecto y preámbulos, con diagnósticos. No descarga inventarios ni paquetes Typst. Los gráficos que piden leer recursos se muestran como código con una advertencia. Este modo no limita la memoria ni el tiempo de ejecución del compilador nativo.
El presupuesto del host es de 1 GiB por defecto. El almacenamiento se reserva antes de asignarlo. Los espacios de trabajo de página se liberan al terminar; el grafo y los catálogos retenidos siguen consumiendo memoria al crecer el proyecto. Los trabajadores coordinan la admisión. Un rechazo indica la operación que falló y las opciones para corregirla.
--memory=ram se detiene al alcanzar el presupuesto gestionado. --memory=disk permite usar archivos temporales mapeados en memoria para el almacenamiento de trabajo gestionado. Los datos retenidos del host siguen contando contra RAM. --disk-budget limita el almacenamiento mapeado y la política deja una reserva de disco. Un comando no interactivo nunca espera una respuesta. GUIDEDOG_AVAILABLE_MIB permite indicar el margen disponible conocido de la máquina.
--max-depth, --max-nodes y --stack-kib limitan el trabajo documental. Cambiar un límite invalida la lectura y salida almacenadas. La profundidad y la capacidad de pila deben ser coherentes. Las asignaciones nativas de Graphviz, tree-sitter y Typst quedan fuera del presupuesto del host. Use límites del sistema operativo cuando necesite un máximo estricto. Véanse Mensajes de error y Memoria y propiedad.
Verificación y proyectos reales¶
tools/sphinxdiff compara 42 raíces de pruebas fijadas de Sphinx: páginas, identificadores, enlaces del cuerpo, inventarios, numeración y diagnósticos. Los resultados guardados y su README explican diferencias deliberadas, como posiciones de origen precisas, numeración estable en orden de lectura y avisos explícitos por contenido sin procesar específico de un formato que se ha omitido.
La validación remota del 1 de octubre de 2026 ejecutó builds limpios y sin cambios de HTML y PDF para CPython, Django y Flask. Los doce terminaron correctamente y conservaron los resultados de diagnósticos y enlaces de referencia. También pasaron 1,039 pruebas Linux y 94 pruebas específicas con AddressSanitizer.
Estos proyectos contienen construcciones de extensiones Python no admitidas. Sus diagnósticos siguen formando parte de las pruebas. Un estado de salida cero no significa que se hayan reproducido todas sus directivas privadas. Use -W si la publicación exige ausencia de diagnósticos.
Las mediciones históricas y revisiones de fuentes se conservan en docs/manual/evidence/manuals.md. El informe remoto más reciente está en build/review-remote-20261001/report.txt. Estas mediciones describen las cargas registradas, no límites universales de velocidad o memoria.