Guidedog / Documentación 0.2.0

Referencia de la línea de comandos¶

La interfaz de línea de comandos de guidedog permite gestionar, compilar, previsualizar, traducir y convertir proyectos de documentación.

Sintaxis general¶

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

Códigos de salida¶

Tabla 6 Estados de salida¶
Código de salida	Condición
`0`	Éxito: todas las operaciones terminaron sin errores pendientes.
`1`	Error de compilación o conversión, o advertencias tratadas como errores con `-W`.
`2`	Sintaxis de línea de comandos incorrecta o una opción desconocida.
`3`	Se alcanzó un límite de recursos o no había memoria disponible.
`4`	Falló una operación de archivo o un compilador externo.
`5`	Error interno; el diagnóstico explica cómo comunicarlo.
`70`	Se produjo un fallo fatal; la publicación anterior sigue disponible.

Resumen de comandos¶

Tabla 7 Comandos de la CLI¶
Comando	Función
`quickstart [DIR]`	Crea un proyecto con plantillas y configuración accesibles para su edición.
`build [BUILDER] [DIR]`	Compila el proyecto en el formato de salida solicitado.
`serve [DIR]`	Inicia un servidor HTTP local que recompila al cambiar los archivos.
`clean [DIR]`	Elimina los archivos generados y las cachés.
`convert INPUT`	Convierte directamente un archivo o la entrada estándar.
`migrate [conf.py]`	Convierte un `conf.py` de Sphinx en un `conf.toml` declarativo.
`intl <update\|stat>`	Actualiza los catálogos PO o informa del progreso de traducción.
`formats`	Enumera los lectores, renderizadores y datos de conformidad de formatos incluidos.
`gds <COMMAND>`	Gestiona los registros de diseño de Guidedog Discussions y su ciclo de vida.

guidedog quickstart¶

Crea un directorio con conf.toml, index.rst, plantillas en _templates/ y estilos en _static/:

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

Opciones:

-q: Omite las preguntas interactivas y usa los valores de la línea de comandos.
-p, --project NAME: Define el nombre visible del proyecto.
-a, --author NAME: Define el nombre del autor o de la organización.
-v VERSION: Define la versión breve, por ejemplo 1.0.
-r RELEASE: Define el identificador completo, por ejemplo 1.0.0-rc1.
-l LANGUAGE: Define el idioma del proyecto; el valor predeterminado es en.
--sep: Crea directorios separados source/ y build/.
--suffix EXT: Define la extensión de los documentos; el valor predeterminado es .rst.

guidedog build¶

Coordina la lectura, la resolución de índices y referencias, y la publicación:

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

Generadores disponibles:

html: Genera un sitio HTML con búsqueda y navegación.
dirhtml: Genera URL de tipo directorio, como dir/index.html.
singlehtml: Reúne todos los documentos en una página HTML.
pdf: Compone libros PDF con Typst; también acepta latex y latexpdf.
text: Genera un archivo de texto por documento.
gettext: Extrae las cadenas traducibles a plantillas POT de GNU gettext.
dummy: Analiza los documentos y resuelve sus referencias sin generar archivos finales.

Opciones de compilación:

-a: Escribe todos los archivos de salida, sin considerar las fechas de modificación.
-E: Reconstruye el entorno sin usar el estado almacenado en caché.
-W: Hace fallar la compilación si hay advertencias.
--keep-going: Con -W, procesa los documentos restantes para informar de todos los errores.
-n: Advierte de todas las referencias cruzadas sin resolver.
-j N / -j auto: Define los hilos de análisis; auto usa el número de núcleos de CPU.
-D name=value: Sobrescribe una opción de conf.toml para esta ejecución, como -D language=de.
-D table.key=value: Fija una clave de un ajuste de tipo tabla, como html_context, y conserva las demás, como hace sphinx-build.
-t TAG: Define una etiqueta para las directivas only.
-c DIR: Indica el directorio que contiene conf.toml.
-C: Compila sin cargar ningún conf.toml.
-v: Muestra información adicional y estadísticas de tiempo.
-q: Muestra solo advertencias y errores.
--color=always|never|auto: Controla los colores ANSI del terminal.
--diagnostics=json: Emite diagnósticos JSON para procesamiento automático en la salida de error.
--budget=MIB: Limita la memoria retenida por el gestor del proyecto; por defecto, 1024 MiB.
--memory=ram|disk: Define qué hacer cuando se agota el presupuesto de memoria.
--untrusted: Omite el marcado incrustado sin procesar y desactiva las descargas. Es una política de capacidades, no un aislamiento de procesos.

guidedog serve¶

Inicia un servidor HTTP local que recompila y recarga el navegador al cambiar fuentes, plantillas o recursos:

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

Opciones:

-p, --port PORT: Puerto local; por defecto, 8000.
--host HOST: Dirección IP de escucha; por defecto, 127.0.0.1.

guidedog clean¶

Elimina el directorio de compilación y el estado del entorno en caché:

guidedog clean docs

guidedog convert¶

Convierte un archivo o la entrada estándar sin proyecto ni configuración:

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

Opciones:

-o, --output FILE: Ruta de salida; - indica la salida estándar.
--to FORMAT: Formato de destino: html, pdf o text; también se deduce del nombre.
--from FORMAT: Lector de entrada: rst, commonmark, myst o typst; se deduce también de la extensión.
--force: Sobrescribe el archivo de salida sin preguntar.
--strict: Falla si se emite alguna advertencia.
--raw=allow|omit: Política para el código incrustado sin procesar; por defecto, omit.
--emit-typst FILE: Guarda el código Typst intermedio en un archivo aparte.

guidedog migrate¶

Convierte la configuración Python conf.py de Sphinx en conf.toml declarativo:

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

Opciones:

-o FILE: Escribe en la ruta indicada; - usa la salida estándar.
--force: Sobrescribe el conf.toml existente.

guidedog intl¶

Gestiona los catálogos de traducción de la documentación:

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

Opciones de intl update:

-l, --language LANG: Código del idioma de destino; se puede repetir.
-p, --pot-dir DIR: Ruta de las plantillas POT extraídas.

guidedog formats¶

Muestra los lectores, renderizadores, analizadores de resaltado y resultados de las pruebas de conformidad:

guidedog formats

guidedog gds¶

Gestiona las propuestas de arquitectura (RFC) de Guidedog Discussions:

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback