Quick Start

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

Initialize Your Documentation (One-Time)

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:

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 great-docs.yml with your API structure
4. 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
Discovered 15 public names
Auto-excluding 3 item(s): cli, main, version
  MyClass: class with 8 public methods
  helper_function: function
  ...
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]:
✅ Updated .gitignore to exclude great-docs/ directory

✅ Great Docs initialization complete!

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

1. Creates the great-docs/ directory with all assets (CSS, JS, etc.)
2. Copies your configuration from great-docs.yml
3. Creates landing page from your README.md
4. Discovers and processes CLI documentation (if present)
5. Copies user guide files from user_guide/ directory (if present)
6. Generates llms.txt and llms-full.txt for AI documentation indexing
7. Creates source links JSON for GitHub integration
8. Generates API reference pages
9. Runs quarto render to build the HTML site

The built site is in great-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) place images in the assets/ directory at your project root.

TipEphemeral 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/
    └── ...

ImportantWhat to Commit

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

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

Warning–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

# Build with file watching (auto-rebuild on changes)
great-docs build --watch

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()

What’s Next?

Your documentation site is ready! Here’s what to explore next:

• 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