great-docs setup-github-pages

Set up automatic deployment to GitHub Pages.

great-docs setup-github-pages [OPTIONS]

This command creates a GitHub Actions workflow that automatically builds and deploys your documentation when you push to the main branch.

  • The workflow will:
  • Build docs on every push and pull request
  • Deploy to GitHub Pages on main branch pushes
  • Use Quarto’s official GitHub Action for reliable builds
  • Install dev dependencies (auto-detected from your package manager)

The Python version is automatically detected from your pyproject.toml’s requires-python field. Use --python-version to override.

  • The package manager is auto-detected by checking for lock files:
  • uv.lock -> uses uv (installs dev dependencies automatically)
  • poetry.lock -> uses poetry (installs with dev dependencies)
  • Otherwise -> uses pip with optional extras like [dev,docs]

After running this command, commit the workflow file and enable GitHub Pages in your repository settings (Settings -> Pages -> Source: GitHub Actions).

Full --help output 
Usage: great-docs setup-github-pages [OPTIONS]

  Set up automatic deployment to GitHub Pages.

  This command creates a GitHub Actions workflow that automatically builds and
  deploys your documentation when you push to the main branch.

  The workflow will:
  β€’ Build docs on every push and pull request
  β€’ Deploy to GitHub Pages on main branch pushes
  β€’ Use Quarto's official GitHub Action for reliable builds
  β€’ Install dev dependencies (auto-detected from your package manager)

  The Python version is automatically detected from your pyproject.toml's
  `requires-python` field. Use '--python-version' to override.

  The package manager is auto-detected by checking for lock files: β€’ uv.lock
  -> uses uv (installs dev dependencies automatically) β€’ poetry.lock -> uses
  poetry (installs with dev dependencies) β€’ Otherwise -> uses pip with
  optional extras like [dev,docs]

  After running this command, commit the workflow file and enable GitHub Pages
  in your repository settings (Settings -> Pages -> Source: GitHub Actions).

  Examples:
    great-docs setup-github-pages                     # Auto-detect everything
    great-docs setup-github-pages --main-branch dev   # Deploy from 'dev' branch
    great-docs setup-github-pages --python-version 3.12
    great-docs setup-github-pages --package-manager uv
    great-docs setup-github-pages --force             # Overwrite existing workflow
    great-docs setup-github-pages --install-from-main # Use GitHub main branch

Options:
  --project-path DIRECTORY        Path to your project root directory
                                  (default: current directory)
  --main-branch TEXT              Main branch name for deployment (default:
                                  main)
  --python-version TEXT           Python version for CI (default: auto-detect
                                  from pyproject.toml, or 3.11)
  --package-manager [auto|pip|uv|poetry]
                                  Package manager for installing dependencies
                                  (default: auto-detect)
  --force                         Overwrite existing workflow file without
                                  prompting
  --install-from-main             Install Great Docs from GitHub main branch
                                  instead of PyPI release
  --help                          Show this message and exit.

Options

--project-path: DIRECTORY
Path to your project root directory (default: current directory)
--main-branch: TEXT = main
Main branch name for deployment (default: main)
--python-version: TEXT
Python version for CI (default: auto-detect from pyproject.toml, or 3.11)
--package-manager: CHOICE = auto
Package manager for installing dependencies (default: auto-detect)
--force
Overwrite existing workflow file without prompting
--install-from-main
Install Great Docs from GitHub main branch instead of PyPI release

Examples

  great-docs setup-github-pages                     # Auto-detect everything
  great-docs setup-github-pages --main-branch dev   # Deploy from 'dev' branch
  great-docs setup-github-pages --python-version 3.12
  great-docs setup-github-pages --package-manager uv
  great-docs setup-github-pages --force             # Overwrite existing workflow
  great-docs setup-github-pages --install-from-main # Use GitHub main branch