Guidedog / Documentation 0.2.0

Command-line reference¶

The guidedog executable provides a complete command-line interface for managing, building, previewing, translating, and converting documentation projects.

General syntax¶

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

Exit codes¶

Table 6 Exit statuses¶
Exit code	Condition
`0`	Success: all operations completed with no unhandled errors.
`1`	Build or conversion error (or warnings treated as errors via `-W`).
`2`	Command-line syntax error, invalid flag, or unrecognized option.
`3`	A configured resource limit was reached, or memory was unavailable.
`4`	A file operation or external compiler failed.
`5`	An internal error; the diagnostic explains how to report it.
`70`	A crash; the previous published output remains available.

Commands overview¶

Table 7 CLI commands¶
Command	Purpose
`quickstart [DIR]`	Initializes a new documentation project with visible templates and configuration.
`build [BUILDER] [DIR]`	Builds the documentation project into the requested output target.
`serve [DIR]`	Starts a local HTTP preview server that rebuilds automatically on file edits.
`clean [DIR]`	Deletes generated build artifacts and caches.
`convert INPUT`	Converts a single document file or standard input stream directly.
`migrate [conf.py]`	Translates an existing Sphinx `conf.py` into declarative `conf.toml`.
`intl <update\|stat>`	Updates translation catalogs (PO) or reports translation completion statistics.
`formats`	Lists all compiled readers, renderers, and format conformance specifications.
`gds <COMMAND>`	Manages Guidedog Discussions architectural RFC records and lifecycles.

guidedog quickstart¶

Creates a project directory containing conf.toml, index.rst, working templates in _templates/, and styles in _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

Options:

-q: Quiet mode; skips interactive prompts and relies on provided command-line flags.
-p, --project NAME: Sets the project display name.
-a, --author NAME: Sets the author or organization name.
-v VERSION: Sets the short version string (e.g. 1.0).
-r RELEASE: Sets the full release identifier (e.g. 1.0.0-rc1).
-l LANGUAGE: Sets the default project language (default: en).
--sep: Creates separate source/ and build/ directories instead of storing sources at the root.
--suffix EXT: Default source document extension (default: .rst).

guidedog build¶

Coordinates the reading of sources, resolution of toctrees and cross-references, and publication of final output artifacts:

# 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

Supported builders:

html: Generates a complete HTML site with search and navigation.
dirhtml: Generates directory-style HTML URLs (dir/index.html).
singlehtml: Compiles all documents into a single contiguous HTML page.
pdf: Typesets PDF books using Typst (aliases: latex, latexpdf).
text: Generates plain text files for each document.
gettext: Extracts translatable strings into GNU gettext POT templates.
dummy: Parses and resolves document trees without writing final files (syntax check).

Build options:

-a: Writes all output files, ignoring modification timestamps.
-E: Rebuilds the environment from scratch, ignoring cached state.
-W: Treats all warnings as build failures.
--keep-going: With -W, continues compiling remaining documents to report all errors before exiting.
-n: Nitpicky mode; generates warnings for all unresolved cross-reference targets.
-j N / -j auto: Parallel worker count for document parsing (auto matches CPU cores).
-D name=value: Overrides a conf.toml setting for this invocation (e.g. -D language=de).
-D table.key=value: Sets one key of a table setting, such as html_context, and keeps its other keys, as sphinx-build does.
-t TAG: Defines a tag for conditional inclusion in only directives.
-c DIR: Specifies a custom directory containing conf.toml.
-C: Runs the build without loading any conf.toml file.
-v: Verbose mode; displays informational notes and timing statistics.
-q: Quiet mode; shows only warnings and errors.
--color=always|never|auto: Controls ANSI terminal color output.
--diagnostics=json: Emits machine-readable JSON diagnostic reports to standard error.
--budget=MIB: Maximum memory budget held by the project host (default: 1024 MiB).
--memory=ram|disk: Strategy when memory budget is exceeded.
--untrusted: Omits raw embedded markup and disables network fetching. This is a capability policy, not a process sandbox.

guidedog serve¶

Starts a local HTTP web server and file watcher that automatically rebuilds and reloads the browser whenever source documents, templates, or assets change:

# 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

Options:

-p, --port PORT: Local TCP port number to listen on (default: 8000).
--host HOST: IP address to bind to (default: 127.0.0.1).

guidedog clean¶

Deletes the build directory and all cached environment state:

guidedog clean docs

guidedog convert¶

Converts a standalone file or standard input stream directly, without requiring a project directory or configuration:

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

Options:

-o, --output FILE: Output file path, or - for standard output.
--to FORMAT: Target format (html, pdf, text; inferred from output filename).
--from FORMAT: Source reader (rst, commonmark, myst, typst; inferred from input suffix).
--force: Overwrites an existing output file without prompting.
--strict: Fails if any warnings are emitted.
--raw=allow|omit: Security policy for raw embedded code (default: omit).
--emit-typst FILE: Writes the generated intermediate Typst markup to a separate file.

guidedog migrate¶

Converts a Python Sphinx conf.py file into declarative conf.toml:

# 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

Options:

-o FILE: Writes output to the specified file path (or - for standard output).
--force: Overwrites existing conf.toml files.

guidedog intl¶

Manages multi-lingual document translation catalogs:

# 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

Options for intl update:

-l, --language LANG: Target language code (may be repeated for multiple languages).
-p, --pot-dir DIR: Custom path to extracted POT message templates.

guidedog formats¶

Prints a detailed report of all compiled readers, renderers, syntax highlighting lexers, and specification test suite conformance results:

guidedog formats

guidedog gds¶

Manages Guidedog Discussions architectural design proposals (RFCs):

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