Guidedog¶
Escribe una vez. Explica bien. Publica en la web y en papel.
Guidedog crea un sitio web de documentación y un libro PDF a partir de los mismos archivos reStructuredText o Markdown. Escribes el texto una vez; Guidedog mantiene las dos ediciones al día.
Entra un archivo de texto plano. Guidedog hace con él una página web y una página de libro.
Qué hace¶
- Un sitio web. Páginas con navegación, búsqueda, código resaltado y temas claro y oscuro, a partir de plantillas Jinja que puedes cambiar tanto como quieras.
- Un libro PDF. Capítulos, referencias cruzadas, figuras, tablas, notas al pie e índice, compuestos por Typst con la separación silábica de cada idioma.
- reStructuredText y Markdown. Las directivas, los roles, los toctrees y las referencias cruzadas funcionan como esperan quienes usan Sphinx, y MyST Markdown puede convivir con ellos.
- Traducciones. Los catálogos gettext llevan un proyecto a otros idiomas. El texto en chino, japonés, coreano e hindi se compone correctamente en pantalla y en papel.
- Diagramas, matemáticas y páginas de API. Diagramas de Graphviz, ecuaciones de LaTeX y referencia de la API de Odin leída del código fuente.
- Errores claros. Cada mensaje dice qué está mal, dónde y cómo arreglarlo. Una compilación fallida deja en su sitio el último sitio correcto.
Un solo programa¶
Guidedog es un único binario. No necesitas un entorno de Python, una instalación de LaTeX ni paquetes aparte de temas o extensiones. La configuración es un archivo TOML, y las plantillas son archivos normales de tu proyecto que puedes editar.
Algunas cosas siguen viniendo de fuera. Guidedog puede compilarse con Typst y Graphviz dentro; una compilación sin ellos usa los programas typst y Graphviz instalados en tu sistema. En Linux y macOS también usa algunas bibliotecas del sistema, como libcurl.
Escríbelo, mira ambos¶
A la izquierda está el reStructuredText. A la derecha, lo que Guidedog hizo con él en esta página. El constructor PDF compone las mismas líneas como una página de libro.
.. note::
Guidedog lee tu texto una sola vez.
Los *mismos* archivos se convierten en un **sitio web**
y en un **libro**:
.. list-table::
:header-rows: 1
* - Constructor
- Resultado
* - ``html``
- Un sitio web
* - ``pdf``
- Un libro PDF
Los mismos archivos se convierten en un sitio web y en un libro:
| Constructor | Resultado |
|---|---|
html |
Un sitio web |
pdf |
Un libro PDF |
El manual como libro PDF es un ejemplo del resultado en papel. Se crea con los mismos archivos que el sitio web del manual.
Empezar¶
Descarga el archivo para tu sistema desde la última versión, pon guidedog en tu PATH y crea un proyecto:
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
quickstart escribe conf.toml, index.rst y plantillas que puedes editar. serve vuelve a construir el sitio mientras escribes. El tutorial recorre un primer proyecto. Para compilar Guidedog desde el código fuente, instala Odin y sigue las instrucciones del repositorio.
Discusiones de diseño¶
Las decisiones de diseño de Guidedog están escritas como discusiones numeradas: el problema, las alternativas, la decisión y las pruebas. Puedes leer cada una en la web o descargarla en PDF.