Great Docs

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

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.

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:

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.

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)

Resources

• Full documentation
• llms.txt — Indexed API reference for LLMs
• llms-full.txt — Comprehensive documentation for LLMs
• Configuration guide
• GitHub repository

CLI Reference — great-docs

Contents

• Global options
• init
• build
• preview
• scan
• config
• uninstall
• setup-github-pages

All commands accept --project-path PATH to target a different directory.

Global options

great-docs [OPTIONS] COMMAND [ARGS]

init

One-time setup: create great-docs.yml and auto-discover API.

great-docs init
great-docs init --force   # reset existing config

Creates great-docs.yml with detected package name, module, parser style, and API sections. Safe to run multiple times (no-op if config exists unless --force).

build

Full build pipeline: prepare → render → build HTML.

great-docs build
great-docs build --no-refresh   # skip API rediscovery (faster)
great-docs build --watch        # rebuild on file changes

Output goes to great-docs/_site/. Build streams progress in real-time.

preview

Start a local development server.

great-docs preview
great-docs preview --port 8080

Serves great-docs/_site/ with live reload. Run build first if the site doesn't exist yet.

scan

Preview which API items will be documented.

great-docs scan
great-docs scan --verbose   # show methods and attributes

Useful for verifying what great-docs init will discover before committing to a build.

config

Generate a template great-docs.yml.

great-docs config
great-docs config --force   # overwrite existing

Similar to init but only creates the config file without running any discovery or setup.

uninstall

Remove great-docs.yml and the great-docs/ build directory.

great-docs uninstall

Preserves source files (user_guide/, recipes/, assets/).

setup-github-pages

Create a GitHub Actions workflow for automated deployment.

great-docs setup-github-pages
great-docs setup-github-pages --main-branch main --python-version 3.12

Creates .github/workflows/docs.yml configured for GitHub Pages deployment with proper caching and Quarto installation.

Common Errors — great-docs

Contents

• Import and discovery errors
• Configuration errors
• Build and rendering errors
• Quarto errors
• Deployment errors

Import and discovery errors

Cannot find an object named X

Cause: Object listed in API config but not exported from __init__.py.

Fix: Add from .module import X to the package's __init__.py.

dynamic: true fails with ImportError

Cause: Package is not importable in the current environment.

Fix: Run pip install -e . in the project root, or set dynamic: false in great-docs.yml to use static analysis.

No API items discovered

Cause: Package has no public exports in __init__.py.

Fix: Ensure public classes and functions are imported in __init__.py or listed in __all__.

Wrong items documented

Cause: Re-exported third-party symbols treated as own API.

Fix: Add unwanted items to exclude list in great-docs.yml:

exclude:
  - ThirdPartyClass
  - imported_helper

Configuration errors

module not found

Cause: module key doesn't match the importable package name.

Fix: Use the Python import name, not the PyPI install name. For pip install py-shiny, set module: shiny.

Parser mismatch (garbled docstrings)

Cause: Docstring style doesn't match parser setting.

Fix: Set parser to match your docstrings:

parser: numpy    # Parameters\n----------\narg : type
parser: google   # Args:\n    arg (type): desc
parser: sphinx   # :param arg: desc\n:type arg: type

CLI reference not generated

Cause: cli.module points to wrong module or the Click app isn't findable.

Fix: Verify cli.module and cli.name:

cli:
  enabled: true
  module: my_package.cli # must contain a Click group/command
  name: my-cli # the CLI entry point name

Build and rendering errors

great-docs/ directory has stale content

Cause: Edited files inside great-docs/ directly.

Fix: Delete great-docs/ and rebuild. Never edit the build directory — it's overwritten on every build.

User guide pages in wrong order

Cause: Missing or inconsistent numeric prefixes.

Fix: Use 2-digit prefixes: 00-intro.qmd, 01-install.qmd, 02-quickstart.qmd. Gaps are fine (00, 05, 10).

Missing cross-references

Cause: %seealso directive references items not in the API.

Fix: Ensure referenced items are exported and not in exclude.

Source links point to wrong branch

Cause: source.branch doesn't match the repository default.

Fix:

source:
  branch: main # or "master", "develop", etc.

Quarto errors

quarto: command not found

Cause: Quarto is not installed or not on PATH.

Fix: Install from https://quarto.org/docs/get-started/ and ensure quarto --version works in the terminal.

Quarto render fails with YAML error

Cause: Generated _quarto.yml has invalid syntax, usually from special characters in config values.

Fix: Check great-docs.yml for unquoted special characters. Wrap values with colons, brackets, or quotes in double quotes:

announcement:
  content: "Version 2.0: now with more features!"

Quarto render fails with missing bibliography

Cause: .qmd files reference a .bib file that doesn't exist.

Fix: Remove the bibliography field from .qmd frontmatter or create the referenced .bib file.

Deployment errors

GitHub Pages shows 404

Cause: Workflow deploys from wrong directory or branch.

Fix: Run great-docs setup-github-pages to regenerate the workflow. Ensure GitHub Pages is configured to deploy from GitHub Actions (Settings → Pages → Source → GitHub Actions).

Site URL incorrect in links

Cause: site-url not set in Quarto config.

Fix: Great Docs auto-detects this from pyproject.toml URLs. Add a Documentation URL:

[project.urls]
Documentation = "https://my-org.github.io/my-package/"

Changelog empty

Cause: No GitHub Releases exist, or GITHUB_TOKEN not available in CI.

Fix: Create at least one GitHub Release, or set changelog: {enabled: false} to disable.

Configuration Reference — great-docs.yml

Contents

• Metadata and package info
• GitHub and source links
• Navigation and theming
• Logo, favicon, and hero
• Content organization
• Features
• Advanced

All keys are optional. Defaults are auto-detected from pyproject.toml.

Metadata and package info

GitHub and source links

Navigation and theming

Logo, favicon, and hero

Logo auto-detection looks for assets/logo.svg, assets/logo-dark.svg, etc.

Content organization

Features

Advanced

Example: minimal config

# great-docs.yml
parser: numpy

Example: fully customized config

# great-docs.yml
module: my_package
display_name: My Package
parser: google
dynamic: true
exclude:
  - _InternalClass
  - _helper_fn

navbar_style: sky
content_style: lilac
dark_mode_toggle: true

logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
hero:
  enabled: true
  tagline: "Beautiful documentation for Python"

announcement:
  content: "v2.0 released!"
  type: info
  dismissable: true

cli:
  enabled: true
  module: my_package.cli
  name: my-cli

changelog:
  enabled: true

sections:
  - title: Examples
    dir: examples

skill:
  enabled: true