great-docs build

Build your documentation site

great-docs build [OPTIONS]

Requires a configuration such as docs/great-docs.yml (run great-docs init first). This is the only command you need day-to-day and in CI.

Creates the docs/_quarto/default/ Quarto project, copies assets, and publishes the site to docs/_site/. Historical projects use docs/_quarto/<tag>/. These generated directories should not be committed. Use --config website/great-docs.yml for a custom source directory.

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. By default it preserves the checkout’s deployment path under the current directory, such as 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 a configuration such as 'docs/great-docs.yml' (run 'great-docs
  init' first). This is the only command you need day-to-day and in CI.

  Creates the 'docs/_quarto/default/' Quarto project, copies assets, and
  publishes the site to 'docs/_site/'. Historical projects use
  'docs/_quarto/<tag>/'. These generated directories should not be committed.
  Use '--config website/great-docs.yml' for a custom source directory.

  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'. By default it preserves the checkout's
  deployment path under the current directory, such as '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 --from-repo output (default: the
                            checkout deployment path, e.g. 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
  --config FILE             Path to the project configuration file
  --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 --from-repo output (default: the checkout deployment path, e.g. 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
--config: FILE: Path to the project configuration file

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