Guidedog¶
English · 简体中文 · 日本語 · 한국어 · हिन्दी · Español · Deutsch
Escriba una vez. Explique con claridad. Publique en la web y en papel.
Guidedog genera sitios de documentación HTML y libros PDF a partir de reStructuredText y Markdown. Está escrito en Odin. El motor de conversión se llama Guidedoc y Typst compone las páginas PDF. No requiere Python ni LaTeX.
El flujo de escritura se inspira en Sphinx, pero Guidedog es un sistema independiente. Usa TOML declarativo y extracción estática de API. Nunca ejecuta configuración ni extensiones Python. No pretende ser completamente compatible con Sphinx.
Crear un proyecto¶
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
El proyecto contiene conf.toml, index.rst, _templates/layout.html, _templates/book.typ y _static/. Las plantillas son archivos editables. HTML ofrece navegación, búsqueda, código resaltado, diagramas y ecuaciones. PDF ofrece capítulos, referencias, figuras, índices y composición adaptada al idioma.
El tema predeterminado es claro; también puede elegir oscuro o el del sistema. La portada del manual y el resumen del repositorio detectan el idioma del navegador. La elección guardada tiene prioridad y se respetan los enlaces directos a una edición o capítulo.
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
Instalar¶
Cada versión incluye un archivo comprimido para Linux (x86-64 y ARM64), macOS (Apple silicon e Intel) y Windows (x86-64). Cada archivo trae Typst, Graphviz y tree-sitter, así que no hace falta instalar nada más para construir sitios y libros. Linux necesita glibc 2.35 o posterior y libcurl; macOS, la versión 12 o posterior. Descargue el archivo de su sistema y SHA256SUMS, compruébelo e instálelo:
sha256sum -c --ignore-missing SHA256SUMS # on macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf guidedog-linux-amd64.tar.gz
sudo install guidedog-linux-amd64/guidedog /usr/local/bin/
En macOS, instale desde el tap oficial de Guidedog para Homebrew. Homebrew elige el archivo para Apple silicon o Intel. El tap también admite Linux:
brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version
En Windows, descomprima el archivo y añada su carpeta a PATH; deje las DLL de Graphviz y config8 junto a guidedog.exe. Los programas no están firmados: en macOS, quite la cuarentena de una descarga del navegador con xattr -d com.apple.quarantine guidedog. Las notas de la versión describen los límites de cada plataforma.
Compilar desde las fuentes¶
Instale Odin dev-2026-10 (tools/install-toolchain.sh odin DIR lo descarga y lo verifica), un compilador de C y, en Linux, los paquetes de desarrollo de libcurl, expat y zlib. Compile primero las bibliotecas nativas y después Guidedog:
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
Después, build/guidedog usa para PDF un Typst 0.15.1 instalado. Para integrar el compilador de Typst como hacen las versiones publicadas, instale Rust y Cargo y ejecute:
native/typst_bridge/build.sh
tools/release/build.sh --release --typst-bridge
En Windows, use Git Bash con las herramientas de C++ de Visual Studio y LLVM. Graphviz no tiene compilación estática para Windows, así que ejecute native/graphviz/windows.sh en lugar de build.sh: instala las DLL oficiales de Graphviz 16.1.0, que tools/release/build.sh copia junto a build/guidedog.exe. tools/release/suites.sh ejecuta las pruebas y RELEASING.md describe el proceso de publicación.
Traducir con Guidedog¶
mkdir -p docs/manual/_editions
build/guidedog build -b gettext docs/manual docs/manual/locales/templates -W
build/guidedog intl update -p docs/manual/locales/templates \
-l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog intl stat -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog build -b html docs/manual docs/manual/_editions/de \
-D language=de -D 'html_extra_path=[]' -W
Traduzca y revise los valores msgstr de los archivos PO. Guidedog extrae POT, fusiona catálogos, informa del progreso y compila cada edición; no redacta traducciones. Mantenga comandos, rutas, código, nombres de API y destinos de referencia. Solo se traducen el manual y el resumen del repositorio; API y GDS siguen en inglés. Véanse las instrucciones de compilación para reunir las ediciones y los PDF.
En GitHub, elija el idioma del README con los enlaces de arriba. La selección automática funciona en el sitio generado.
Leer e integrar¶
- Manual: tutoriales, temas, tareas, referencia y funcionamiento interno.
- Referencia API: generada del código Odin e incluida como apéndice del PDF del manual.
Guía de la biblioteca: espacios de trabajo del llamador, memoria y ejemplos de conversión.- Plantillas: personalizar HTML con Jinja y libros con Typst.
GDS: registros numerados de diseño y decisiones de implementación.Revisión beta: correcciones, verificación, alcance y requisitos de publicación pendientes.
Guidedoc usa almacenamiento del llamador y devuelve diagnósticos estructurados. El gestor se ocupa de archivos, presupuestos, caché, publicación y compiladores nativos. --untrusted limita capacidades; no aísla procesos ni limita todos los recursos nativos. La beta está dirigida a proyectos de confianza en macOS y Linux.
Créditos y licencia¶
Creado por Vikrant Rathore, con la colaboración de Ronak Rathore y Kanak Rathore. Se agradecen las contribuciones mediante issues y pull requests. Los créditos usan nombres o identificadores, sin direcciones personales de correo; la identidad de Git se gestiona por separado.
Gracias a Sphinx y Georg Brandl, Docutils y David Goodger, Typst, Tree-sitter y Max Brunsfeld, Graphviz, Ginger Bill y la comunidad Odin.
Guidedog se distribuye bajo la Licencia Pública General Affero de GNU v3.0 o posterior (AGPL-3.0-or-later). Para otras condiciones de licencia, contacte con los autores. NOTICE explica cómo hacerlo y enumera los componentes de terceros que conservan sus propias licencias, como las fuentes incluidas.
Un permiso adicional autoriza enlazar y distribuir Guidedog junto con Graphviz; consulte NOTICE.