Command-line reference ====================== The ``guidedog`` executable provides a complete command-line interface for managing, building, previewing, translating, and converting documentation projects. General syntax -------------- .. code-block:: sh guidedog [arguments] [options] guidedog --version guidedog --help Exit codes ---------- .. list-table:: Exit statuses :header-rows: 1 :widths: 20 80 * - 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 ----------------- .. list-table:: CLI commands :header-rows: 1 :widths: 30 70 * - 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 `` - Updates translation catalogs (PO) or reports translation completion statistics. * - ``formats`` - Lists all compiled readers, renderers, and format conformance specifications. * - ``gds `` - 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/``: .. code-block:: sh # 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: .. code-block:: sh # 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: .. code-block:: sh # 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: .. code-block:: sh guidedog clean docs guidedog convert ---------------- Converts a standalone file or standard input stream directly, without requiring a project directory or configuration: .. code-block:: sh # 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``: .. code-block:: sh # 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: .. code-block:: sh # 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: .. code-block:: sh guidedog formats guidedog gds ------------ Manages Guidedog Discussions architectural design proposals (RFCs): .. code-block:: sh 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