# Guidedog

[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [हिन्दी](README.hi.md) · [Español](README.es.md) · [Deutsch](README.de.md)

**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

```sh
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.

```sh
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
```

## Instalar

Cada [versión](https://github.com/insanai/guidedog/releases) 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:

```sh
sha256sum -c --ignore-missing SHA256SUMS      # en 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](https://github.com/insanai/homebrew-guidedog). Homebrew elige el archivo para Apple silicon o Intel. El tap también admite Linux:

```sh
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:

```sh
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:

```sh
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](RELEASING.md) describe el proceso de publicación.

## Traducir con Guidedog

```sh
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](docs/manual/README.md) 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](docs/manual/index.rst): tutoriales, temas, tareas, referencia y funcionamiento interno.
- [Referencia API](docs/api/index.rst): generada del código Odin e incluida como apéndice del PDF del manual.
- [Guía de la biblioteca](lib/README.md): espacios de trabajo del llamador, memoria y ejemplos de conversión.
- [Plantillas](docs/manual/templates.rst): personalizar HTML con Jinja y libros con Typst.
- [GDS](docs/gds/README.md): registros numerados de diseño y decisiones de implementación.
- [Revisión beta](docs/manual/evidence/beta-review-20261011.md): 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](LICENSE) (AGPL-3.0-or-later). Para otras condiciones de licencia, contacte con los autores. [NOTICE](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](NOTICE).