Quick Start

This guide walks you through creating your first documentation site with Great Docs in just a few minutes.

Initialize Your Documentation

Make sure you’ve installed Great Docs first, then navigate to your Python project’s root directory and run:

Terminal

great-docs init

You only need to run this once. It creates great-docs.yml with sensible defaults. After that, great-docs build is the only command you need.

Great Docs will automatically:

Find your package: Auto-detects your package name from pyproject.toml, setup.cfg, setup.py, or directory structure
Discover your API: Finds all public classes, functions, and methods
Create configuration: Generates great-docs.yml with your API structure
Update .gitignore: Optionally adds great-docs/ to exclude build artifacts

You’ll see output like this:

Terminal output

Initializing great-docs...
Detecting docstring style...
Detected numpy docstring style
Found package __init__.py at: my_package/__init__.py
Using __all__ with 15 exports
Auto-excluding 3 item(s): cli, main, version
Categorizing API objects...
MyClass: class with 8 public methods
Testing dynamic introspection mode...
Dynamic introspection mode works for this package
Generated 2 section(s) from reference config
Created /path/to/project/great-docs.yml

The great-docs/ directory is ephemeral and should not be committed to git.
Add 'great-docs/' to .gitignore? [Y/n]: Y
✅ Updated .gitignore to exclude great-docs/ directory

✅ Great Docs initialization complete!

Next steps:
1. Review great-docs.yml to customize your API reference structure
   (Reorder items, add sections, set 'members: false' to exclude methods)
2. Run `great-docs build` to generate and build your documentation site
3. Run `great-docs preview` to view the site locally

Other helpful commands:
  great-docs scan           # Preview API organization
  great-docs build --watch  # Watch for changes and rebuild

Configuration File

The great-docs.yml file contains your API structure and is committed to git. The great-docs/ build directory is ephemeral and should be gitignored.

Customize Your Configuration

Open great-docs.yml and tailor it to your project. Organize API sections, add authors or funding info, set a display_name, add a user_guide directory, etc. See Configuration for all available options.

Build Your Documentation

Build (and rebuild) your docs with:

Terminal

great-docs build

This is the only command you need day-to-day and in CI. It prepares the build directory, configures the API reference, generates supporting files (LLM indexes, source links, changelogs), processes your user guide and custom pages, generates API reference pages, and runs Quarto to render the final HTML site. The output shows each step with its status and timing:

Build output (abbreviated)

━━ Step  1/17 ─ Prepare build directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] great-docs/ ready                                                <0.1s

━━ Step  2/17 ─ Configure API reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] 2 section(s), 15 item(s)                                           1.2s
   ...

━━ Step 14/17 ─ Build site with Quarto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] quarto render                                                     28.4s

━━ Step 17/17 ─ Generate SEO files ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Generated sitemap.xml with 120 URLs
      Generated robots.txt
   [OK] sitemap.xml + robots.txt                                          <0.1s

==============================================================================
|  [OK] Build complete — 17/17 steps                                         |
|  Total time: 35.6s                                                         |
|                                                                            |
|  🎉 Site ready →                                                           |
|     /path/to/project/great-docs/_site/index.html                           |
==============================================================================

The built site is in great-docs/_site/.

Images in README.md

If your README contains images with relative paths (like ![](images/screenshot.png)), they will be copied to the build directory automatically. For the most portable setup (working in both GitHub and your docs site) place images in the assets/ directory at your project root.

Ephemeral Build Directory

The great-docs/ directory is created fresh on each build. You can safely delete it between builds (it will be recreated from great-docs.yml and your source files).

Preview Locally

To preview your documentation with live reload:

Terminal

great-docs preview

This starts a local server and opens your browser. Changes to your documentation files trigger automatic rebuilds.

Project Structure

After initialization and your first build, your project will have:

Project structure

your-project/
├── great-docs.yml           # Configuration (committed to git)
├── great-docs/              # Build directory (gitignored, ephemeral)
│   ├── _quarto.yml          # Generated Quarto config
│   ├── index.qmd            # Landing page (from README.md)
│   ├── great-docs.scss      # Styling
│   ├── github-widget.js     # GitHub stars widget
│   ├── sidebar-filter.js    # API search filter
│   ├── llms.txt             # LLM-friendly docs index
│   ├── llms-full.txt        # Full API docs for LLMs
│   ├── _source_links.json   # Source code links
│   ├── reference/           # API reference pages (generated)
│   │   ├── index.qmd
│   │   ├── MyClass.qmd
│   │   └── ...
│   ├── user-guide/          # Copied from user_guide/
│   ├── scripts/
│   │   └── post-render.py   # HTML post-processing
│   └── _site/               # Built HTML site
│       ├── index.html
│       └── ...
├── user_guide/              # Your narrative docs (optional)
│   ├── 01-installation.qmd
│   └── ...
├── pyproject.toml
├── README.md
└── your_package/
    └── ...

What to Commit

✅ great-docs.yml – Your configuration
✅ user_guide/ – Your narrative documentation
✅ README.md – Your project readme
❌ great-docs/ – Ephemeral build directory (gitignored)

Scan Your API

Before (or after) running init, you can use great-docs scan to preview what Great Docs discovered in your package. It shows every public class, function, constant, and enum, along with whether each item appears in your great-docs.yml reference config:

Terminal

great-docs scan           # Show discovered exports
great-docs scan --verbose  # Include method names for each class

This is useful for auditing your configuration: items marked [x] are included in your docs, while [ ] items are not. You can then add or remove entries in great-docs.yml accordingly.

Command Options

Initialize Options

Terminal

# Initialize a different project
great-docs init --project-path /path/to/project

# Reset config to fresh defaults (deletes existing great-docs.yml)
great-docs init --force

–force Starts From Scratch

great-docs init --force deletes your existing great-docs.yml and generates a brand-new default config. Any customizations you made (authors, sections, display_name, etc.) will be lost. Only use this if you genuinely want to reset.

Build Options

Terminal

# Skip API re-discovery for faster rebuilds
great-docs build --no-refresh

# Watch for file changes and rebuild automatically
great-docs build --watch

# Build only specific versions (multi-version sites)
great-docs build --versions 0.3,dev

# Build only the latest version (skip historical)
great-docs build --latest-only

Preview Options

Terminal

# Preview on the default port (3000)
great-docs preview

# Use a different port
great-docs preview --port 8080

Using the Python API

You can also use Great Docs programmatically:

Python

from great_docs import GreatDocs

# Initialize for current directory
docs = GreatDocs()
docs.install()

# Build documentation
docs.build()

# Preview documentation
docs.preview()

# Or initialize for a specific project
docs = GreatDocs(project_path="/path/to/project")
docs.install()
docs.build()

Next Steps

Your documentation site is ready! If you’re new to writing .qmd files, head to the Authoring QMD Files guide for a thorough introduction to Markdown, frontmatter, callouts, tabsets, and all the other building blocks available to you.

Authoring QMD Files covers Markdown, frontmatter, callouts, and other building blocks
Configuration covers customizing Great Docs behavior
API Documentation explains how API discovery works
CLI Documentation covers Click CLI documentation
User Guides explains how to add narrative documentation
Deployment covers publishing to GitHub Pages