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