great-docs

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

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

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:

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 or 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.

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 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:

sections:
  - title: Examples
    dir: examples

Customizing appearance

# 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 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:

#!/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:

#!/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
• llms.txt — Indexed API reference for LLMs
• llms-full.txt — Comprehensive documentation for LLMs
• Configuration guide
• GitHub repository