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 docs/great-docs.yml with sensible defaults. After that, great-docs build is the only command you need.

Great Docs will automatically:

  1. Find your package: Auto-detects your package name from pyproject.toml, setup.cfg, setup.py, or directory structure
  2. Discover your API: Finds all public classes, functions, and methods
  3. Create configuration: Generates docs/great-docs.yml with your API structure
  4. Update .gitignore: Excludes docs/_quarto/ and docs/_site/ generated output

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/docs/great-docs.yml

The generated Quarto projects and deployment output should not be committed to git.
✅ Updated .gitignore to exclude docs/_quarto/ and docs/_site/

✅ Great Docs initialization complete!

Next steps:
1. Review docs/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
NoteConfiguration File

Commit docs/great-docs.yml with your API structure. Ignore the generated docs/_quarto/ and docs/_site/ directories.

Customize Your Configuration

Open docs/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.

Resolve documentation source paths from the configuration directory: assets/logo.svg means docs/assets/logo.svg. Keep pyproject.toml, Python sources, and the README at the package root. To use a custom directory, run great-docs init --config website/great-docs.yml, then great-docs build --config website/great-docs.yml. Deploy website/_site/.

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/19 ─ Prepare build directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] docs/_quarto/default/ ready                                                <0.1s

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

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

━━ Step 18/19 ─ Post-render processing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] Version assembly complete                                        <0.1s

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

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

The built site is in docs/_site/.

TipImages 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), keep shared README images at the package root and use paths relative to the README. Put documentation-only images in docs/assets/.

TipEphemeral Build Directory

The docs/_quarto/default/ directory is created fresh on each build. You can safely delete it between builds (it will be recreated from docs/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/
├── docs/
│   ├── great-docs.yml       # Configuration (committed)
│   ├── user_guide/          # Narrative sources (committed)
│   │   └── 01-installation.qmd
│   ├── assets/              # Documentation images (committed)
│   ├── _freeze/             # Cached execution results (committed)
│   ├── _quarto/             # Generated Quarto projects (gitignored)
│   │   └── default/
│   │       ├── _quarto.yml
│   │       ├── reference/
│   │       ├── user-guide/
│   │       └── _site/
│   └── _site/               # Deploy this directory (gitignored)
│       └── index.html
├── pyproject.toml
├── README.md
└── your_package/
    └── ...
ImportantWhat to Commit
  • Commit docs/great-docs.yml for configuration
  • Commit docs/user_guide/ for narrative documentation
  • Commit README.md for the package homepage
  • Commit docs/_freeze/ to reuse execution results
  • Ignore docs/_quarto/ and docs/_site/ generated output

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 docs/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 docs/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 docs/great-docs.yml)
great-docs init --force
Warning–force Starts From Scratch

great-docs init --force deletes your existing docs/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.