---
name: great-docs
description: >
  Generate documentation sites for Python packages with Great Docs.
  Covers init, build, preview, configuration (great-docs.yml), API
  reference, CLI docs, user guides, theming, deployment, and the
  llms.txt agent-context files. Use when creating, configuring,
  building, or troubleshooting Python package documentation.
license: MIT
compatibility: Requires Python >=3.11, Quarto CLI installed.
metadata:
  author: rich-iannone
  version: "2.0"
  tags:
    - documentation
    - python-packages
    - quarto
    - api-reference
    - static-site
---

# Great Docs

A docs generator for Python packages. Introspects your API, renders
reference pages, and produces a Quarto-based static site with user
guides, CLI docs, theming, and more.

## Quick start

```bash
pip install great-docs
# Quarto must also be installed: https://quarto.org/docs/get-started/

cd my-package/        # directory with pyproject.toml
great-docs init       # create great-docs.yml, discover API
great-docs build      # full build -> great-docs/_site/
great-docs preview    # local server on port 3000
```

## Skill directory structure

This skill ships with companion files for agent consumption:

```
skills/great-docs/
├── SKILL.md                ← This file
├── references/
│   ├── config-reference.md ← All great-docs.yml options
│   ├── cli-reference.md    ← CLI commands and arguments
│   └── common-errors.md    ← Error patterns and fixes
├── scripts/
│   ├── setup-env.sh        ← Environment bootstrap script
│   └── run-build.sh        ← Build with validation
└── assets/
    └── config-template.yaml ← Starter great-docs.yml
```

## When to use what

| Need                      | Use                                     |
| ------------------------- | --------------------------------------- |
| Start a new docs site     | `great-docs init`                       |
| Full build from scratch   | `great-docs build`                      |
| Rebuild after edits       | `great-docs build --no-refresh`         |
| Live preview              | `great-docs preview`                    |
| See discoverable API      | `great-docs scan --verbose`             |
| Change docstring parser   | `parser: google` in great-docs.yml      |
| Add CLI reference         | `cli: {enabled: true, module: pkg.cli}` |
| Add a gradient navbar     | `navbar_style: sky`                     |
| Exclude internal symbols  | `exclude: [_InternalClass]`             |
| Add user guide pages      | Create `user_guide/05-topic.qmd`        |
| Add recipes               | Create `recipes/07-topic.qmd`           |
| Set up GitHub Pages CI    | `great-docs setup-github-pages`         |
| Use static analysis       | `dynamic: false` (for tricky imports)   |
| Generate agent skill file | `skill: {enabled: true}`                |

## Core concepts

### Configuration (`great-docs.yml`)

Single YAML file at the project root controls everything. All keys
are optional — sensible defaults are auto-detected from
`pyproject.toml` and package structure.

**Full config reference**: See [references/config-reference.md](references/config-reference.md)

### Build pipeline

The `build` command runs 13 steps in order:

1. Prepare build directory (copy assets, JS, SCSS)
2. Copy user guide from `user_guide/`
3. Copy project `assets/`
4. Refresh API reference (introspect package)
5. Generate `llms.txt` and `llms-full.txt`
6. Generate `skill.md` (if enabled)
7. Generate source links JSON
8. Generate changelog (from GitHub Releases)
9. Generate CLI reference (if enabled)
10. Process user guide (frontmatter, sidebar)
11. Process custom sections
12. Render API reference (`.qmd` files)
13. Run `quarto render` -> `_site/` HTML output

The `great-docs/` directory is **ephemeral** — regenerated on every
build. Never edit files inside it directly.

### Two rendering modes

- **Dynamic** (default): imports the package at runtime for full
  introspection. Requires `pip install -e .` first.
- **Static** (`dynamic: false`): uses griffe for AST-based analysis.
  Use when the package has circular imports, lazy loading, or
  compiled extensions.

Dynamic mode auto-falls-back to static if the import fails.

### Docstring directives

Custom directives inside docstrings use `%` prefix:

```python
def my_function():
    """
    Description.

    %seealso func_a, func_b: related functions, ClassC
    %nodoc
    """
```

- `%seealso name1, name2: desc` — Cross-references in rendered docs
- `%nodoc` — Exclude this item from documentation

## Workflows

### New documentation site

```
Task Progress:
- [ ] Step 1: Install prerequisites
- [ ] Step 2: Initialize configuration
- [ ] Step 3: Customize config
- [ ] Step 4: Build and preview
- [ ] Step 5: Verify output
```

**Step 1**: Ensure `great-docs` and `quarto` are installed. The
target package must be importable (`pip install -e .`).

**Step 2**: Run `great-docs init` from the project root (where
`pyproject.toml` lives). This creates `great-docs.yml`.

**Step 3**: Edit `great-docs.yml` to customize. See
[references/config-reference.md](references/config-reference.md) or
[assets/config-template.yaml](assets/config-template.yaml) for all
options.

**Step 4**: Run `great-docs build` then `great-docs preview`.

**Step 5**: Check the site at `http://localhost:3000`. If errors
occur, see [references/common-errors.md](references/common-errors.md).

### Upgrading Great Docs

```
Task Progress:
- [ ] Step 1: Upgrade the package
- [ ] Step 2: Verify version
- [ ] Step 3: Review changelog
- [ ] Step 4: Rebuild site
```

**Step 1**: Upgrade using whichever tool manages the environment:

| Tool | Command                               |
| ---- | ------------------------------------- |
| pip  | `pip install --upgrade great-docs`    |
| uv   | `uv pip install --upgrade great-docs` |
| pipx | `pipx upgrade great-docs`             |

If the project declares `great-docs` in `pyproject.toml` dependencies,
update the version constraint there and run `uv sync` instead.

**Step 2**: Run `great-docs --version` and confirm it shows the
expected version.

**Step 3**: Check the [release notes](https://github.com/posit-dev/great-docs/releases)
for breaking changes or new configuration options.

**Step 4**: Run `great-docs build` to pick up pipeline, template, or
default-config changes. **Do not re-execute user guide notebooks** —
`great-docs build` regenerates reference pages and templates without
running notebook code, and notebook execution can be very
time-consuming.

### Adding content

**User guide page**: Create `user_guide/NN-title.qmd` with a
2-digit numeric prefix. Auto-discovered on next build.

**Recipe**: Create `recipes/NN-title.qmd`. Same numeric prefix
convention.

**Custom section**: Add to `great-docs.yml`:

```yaml
sections:
  - title: Examples
    dir: examples
```

### Customizing appearance

```yaml
# great-docs.yml
navbar_style: sky # gradient: sky, peach, lilac, mint, etc.
content_style: lilac # content area glow
dark_mode_toggle: true # toggle switch in navbar
logo: assets/logo.svg # or {light: ..., dark: ...}
hero: true # landing page hero section
announcement:
  content: "v2 is out!"
  type: info
  dismissable: true
```

### Troubleshooting a build

1. Run `great-docs build` and read the error output
2. Check [references/common-errors.md](references/common-errors.md) for
   the error pattern
3. Fix the config or source file
4. Rebuild with `great-docs build --no-refresh` (faster, skips API
   rediscovery)
5. If the error persists, try `great-docs build` with full refresh

## Reference files

### Config reference (`references/config-reference.md`)

Complete list of every `great-docs.yml` option with types, defaults,
and examples. Organized by category: metadata, GitHub, navigation,
theming, content, features, and advanced.

### CLI reference (`references/cli-reference.md`)

All CLI commands with arguments and usage examples:

| Command              | Purpose                     |
| -------------------- | --------------------------- |
| `init`               | Create config, discover API |
| `build`              | Full build pipeline         |
| `preview`            | Local dev server            |
| `scan`               | Preview discoverable API    |
| `config`             | Generate template config    |
| `uninstall`          | Remove config and build dir |
| `setup-github-pages` | Create CI/CD workflow       |

### Common errors (`references/common-errors.md`)

Error patterns, causes, and fixes for the most frequent build
failures — import errors, missing exports, config mismatches,
Quarto issues, and more.

## Scripts

### `scripts/setup-env.sh`

Bootstrap a development environment:

```bash
#!/usr/bin/env bash
set -euo pipefail
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pip install great-docs
quarto --version || echo "ERROR: Quarto not installed"
```

### `scripts/run-build.sh`

Build with validation:

```bash
#!/usr/bin/env bash
set -euo pipefail
great-docs build
echo "Build complete. Site at great-docs/_site/"
ls great-docs/_site/index.html && echo "OK: index.html exists"
```

## Configuration template

The `assets/config-template.yaml` provides a starter config with
annotated options. Copy it as `great-docs.yml` and customize.

## Gotchas

1. **Run from project root.** All commands must run from the
   directory containing `great-docs.yml` (and `pyproject.toml`).
2. **`module` vs package name.** The `module` key is the Python
   importable name, not the PyPI name. For `py-shiny`, set
   `module: shiny`.
3. **Circular imports.** Set `dynamic: false` for packages with
   lazy loading or circular aliases.
4. **User guide ordering.** Files need numeric prefixes
   (`00-intro.qmd`, `01-install.qmd`) for deterministic order.
5. **Don't edit `great-docs/` directly.** It's regenerated on every
   build. Edit source files instead.
6. **Quarto required.** If `quarto` is not on `PATH`, the build
   fails at step 13.
7. **Package must be importable.** In dynamic mode, run
   `pip install -e .` before building.
8. **Don't re-execute notebooks after upgrading.** A plain
   `great-docs build` is enough — it regenerates reference pages and
   templates without running notebook code. Notebook execution is
   time-consuming and is not required for upgrades.

## Capabilities and boundaries

**What agents can configure:**

- All `great-docs.yml` settings
- User guide `.qmd` pages in `user_guide/`
- Recipe `.qmd` pages in `recipes/`
- Custom section `.qmd` pages
- Logo, favicon, and other assets
- Custom CSS/SCSS overrides
- Docstring directives (`%seealso`, `%nodoc`)

**Requires human setup:**

- `pip install great-docs` and Quarto installation
- `pip install -e .` for the target package
- GitHub Pages or hosting deployment
- Custom domain DNS
- GitHub access tokens (for changelog)

## Related skills

This is the general-purpose skill for Great Docs. For deeper
guidance on specific tasks, use these companion skills:

| Task                        | Skill               | When to use                                                   |
| --------------------------- | ------------------- | ------------------------------------------------------------- |
| Write user guide pages      | `write-user-guide`  | Creating or editing `.qmd` pages in `user_guide/`             |
| Improve docstrings          | `revise-docstrings` | Auditing or rewriting Python docstrings for the API reference |
| Configure the site          | `configure-site`    | Customizing `great-docs.yml` theming, features, and layout    |
| Create or distribute skills | `author-skills`     | Writing SKILL.md files, setting up multi-skill distribution   |

## Resources

- [Full documentation](https://posit-dev.github.io/great-docs/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Configuration guide](https://posit-dev.github.io/great-docs/user-guide/03-configuration.html)
- [GitHub repository](https://github.com/posit-dev/great-docs)
