great-docs build

Build your documentation site.

great-docs build [OPTIONS]

Requires great-docs.yml to exist (run great-docs init first). This is the only command you need day-to-day and in CI.

Creates the great-docs/ build directory, copies all assets, and builds the documentation site. The build directory is ephemeral and should not be committed to version control.

Use --project-path to point to a project in a different directory. Use --watch to automatically rebuild when source files change.

Use --no-refresh to skip API discovery for faster rebuilds when your package’s public API hasn’t changed.

When multi-version documentation is configured, use --versions to build only specific versions, or --latest-only to skip historical versions.

Use --from-repo to build documentation from a remote Git repository. This clones the repo into a temporary directory, creates an isolated virtual environment, installs the package and great-docs, builds the site, and copies the output to --output-dir (or ./great-docs/_site).

Add --preview to automatically start a local server after a --from-repo build completes, opening the site in your browser.

Full --help output

Usage: great-docs build [OPTIONS]

  Build your documentation site.

  Requires 'great-docs.yml' to exist (run 'great-docs init' first). This is
  the only command you need day-to-day and in CI.

  Creates the 'great-docs/' build directory, copies all assets, and builds the
  documentation site. The build directory is ephemeral and should not be
  committed to version control.

  Use '--project-path' to point to a project in a different directory. Use '--
  watch' to automatically rebuild when source files change.

  Use '--no-refresh' to skip API discovery for faster rebuilds when your
  package's public API hasn't changed.

  When multi-version documentation is configured, use '--versions' to build
  only specific versions, or '--latest-only' to skip historical versions.

  Use '--from-repo' to build documentation from a remote Git repository. This
  clones the repo into a temporary directory, creates an isolated virtual
  environment, installs the package and great-docs, builds the site, and
  copies the output to '--output-dir' (or './great-docs/_site').

  Add '--preview' to automatically start a local server after a '--from-repo'
  build completes, opening the site in your browser.

  Examples:
    great-docs build                      # Full build with API refresh
    great-docs build --no-refresh         # Fast rebuild (skip API discovery)
    great-docs build --watch              # Rebuild on file changes
    great-docs build --versions 0.3,dev   # Build specific versions only
    great-docs build --latest-only        # Build only the latest version
    great-docs build --project-path ../pkg
    great-docs build --from-repo https://github.com/owner/pkg.git
    great-docs build --from-repo git@github.com:owner/pkg.git --branch v1.0
    great-docs build --from-repo https://github.com/owner/pkg.git --output-dir ./site
    great-docs build --from-repo https://github.com/owner/pkg.git --shallow
    great-docs build --from-repo https://github.com/owner/pkg.git --preview

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --watch                   Watch for changes and rebuild automatically
  --no-refresh              Skip re-discovering package exports (faster
                            rebuild when API unchanged)
  --versions TEXT           Build only specific versions (comma-separated
                            tags, e.g. '0.3,dev')
  --latest-only             Build only the latest version (skip historical
                            versions)
  --from-repo TEXT          Clone a remote Git repository and build its docs
                            (HTTPS or SSH URL)
  --branch TEXT             Branch or tag to check out when using --from-repo
                            (default: repo default)
  --output-dir DIRECTORY    Where to copy the built site when using --from-
                            repo (default: ./great-docs/_site)
  --shallow                 Force shallow clone with --from-repo (fastest, but
                            no versioned docs or page dates)
  --preview                 Start a preview server after building with --from-
                            repo
  --help                    Show this message and exit.

Options

--project-path: DIRECTORY

Path to your project root directory (default: current directory)

--watch

Watch for changes and rebuild automatically

--no-refresh

Skip re-discovering package exports (faster rebuild when API unchanged)

--versions: TEXT

Build only specific versions (comma-separated tags, e.g. 0.3,dev)

--latest-only

Build only the latest version (skip historical versions)

--from-repo: TEXT

Clone a remote Git repository and build its docs (HTTPS or SSH URL)

--branch: TEXT

Branch or tag to check out when using --from-repo (default: repo default)

--output-dir: DIRECTORY

Where to copy the built site when using --from-repo (default: ./great-docs/_site)

--shallow

Force shallow clone with --from-repo (fastest, but no versioned docs or page dates)

--preview

Start a preview server after building with --from-repo

Examples

  great-docs build                      # Full build with API refresh
  great-docs build --no-refresh         # Fast rebuild (skip API discovery)
  great-docs build --watch              # Rebuild on file changes
  great-docs build --versions 0.3,dev   # Build specific versions only
  great-docs build --latest-only        # Build only the latest version
  great-docs build --project-path ../pkg
  great-docs build --from-repo https://github.com/owner/pkg.git
  great-docs build --from-repo git@github.com:owner/pkg.git --branch v1.0
  great-docs build --from-repo https://github.com/owner/pkg.git --output-dir ./site
  great-docs build --from-repo https://github.com/owner/pkg.git --shallow
  great-docs build --from-repo https://github.com/owner/pkg.git --preview