Documentation sites for Python packages: start simple, go deep
Quickstart ยท Features ยท Configuration ยท Recipes ยท Docs
--- > [!TIP] > **๐บ Featured on Talk Python:** [**the "Great Docs" live stream**](https://www.youtube.com/live/rj2hY2Bsi30) > > See Great Docs in action and hear the story behind it: a full walkthrough on Talk Python. > >
Great Docs turns your Python package into a polished documentation site in minutes. It auto-discovers your public API, detects your docstring format, generates structured reference pages, and renders a modern site, all from a single command. When you're ready to customize, there's a deep set of tools and options waiting for you.
And it's battle-tested: every release runs against [300+ synthetic packages](https://posit-dev.github.io/gdg/) in the Great Docs Gauntlet, backed by a suite of 26,000+ tests.
From zero to a live site in three commands.
A 22-second tour of a generated site: going through some of the site's many useful pages. Great Docs documents itself -> explore the live site.
## Why Great Docs? Writing documentation shouldn't be harder than writing the code it describes. Most documentation generators require you to author page templates, organize content by hand, and wire up a build system. Great Docs inverts that: point it at a Python package and get a great site right away, then explore further at your own pace. - **Instant setup**: `great-docs init` inspects your package and generates a complete config - **Smart defaults**: API reference pages are created automatically from your code (no manual authoring needed) - **Real documentation, not stubs**: renders full parameter tables, return types, examples, and cross-references from your existing docstrings - **Looks great out of the box**: gradient navbars, dark mode, responsive layout, GitHub widget, sidebar search, keyboard navigation - **Deep when you need it**: user guides, multi-version docs, freeze caching, link checking, proofreading, SEO, internationalization (20+ languages), and more (all opt-in) - **AI-ready**: auto-generates `llms.txt`, agent skills, and markdown pages for LLM consumption - **Deploys anywhere**: one command creates a GitHub Actions workflow for GitHub Pages ## How It Compares Most Python documentation tools hand you a framework and ask you to assemble the site yourself. Great Docs assembles a complete site for you first, then gets out of the way when you want control. | | Great Docs | Sphinx | MkDocs | pdoc | | --- | :---: | :---: | :---: | :---: | | Polished site with **zero config** | โ | โ | โ | โ | | API reference from your docstrings | โ | โ | plugin | โ | | Prose guides, recipes, custom pages | โ | โ | โ | โ | | Click CLI **and** MCP server reference | โ | โ | โ | โ | | Dark mode, search, theming built in | โ | theme | theme | basic | | AI-ready: `llms.txt`, agent skills | โ | โ | โ | โ | | Link check, lint, proofread, SEO | โ | partial | plugins | โ | Great Docs is built on [Quarto](https://quarto.org/), so you get its rendering power (executable code, math, diagrams) without having to wire any of it up. ## Get Started in 60 Seconds > [!IMPORTANT] > Great Docs needs two things on your system: **Python 3.11+** and **[Quarto](https://quarto.org/docs/get-started/)**, the rendering engine. Quarto is a separate, one-time install (it isn't a Python package), so set it up before running the commands below. See [Requirements](#requirements) for details. ### Install ```bash pip install great-docs ``` ### Initialize, build, and preview ```bash cd your-python-package great-docs init # auto-detect package, generate config great-docs build # generate and render the site great-docs preview # open in your browser at localhost:3000 ``` That's it. Your documentation site is ready. ## What Gets Generated Every site built by Great Docs includes: ### Landing Page Your README is transformed into a landing page with a hero section, metadata sidebar (authors, license, links), and quick-start instructions. ### API Reference Classes, functions, methods, and attributes are automatically organized into categorized sections. Large classes get dedicated method pages. Every item links back to source code on GitHub.
| **Documentation Generation** - Auto-discovers exports via `__all__`, `dir()`, or static analysis - Detects NumPy, Google, and Sphinx docstring formats - 13 object types with smart categorization - CLI documentation (Python Click, Go, and Rust) - User Guide pages from `docs/user_guide/` directory - Custom sections (recipes, blog, tutorials, etc.) - Custom HTML pages with passthrough or raw layouts - Multi-version documentation with version selector - Video embeds (YouTube, Vimeo, local files) - Interactive Marimo notebooks - Mermaid and D2 diagram pre-rendering (light + dark variants) - Freeze/cache support for expensive computations | **Site Features** - Dark mode toggle with persistent preference - Lightbox image viewer (zoom, pan, galleries) - GitHub widget with live star/fork counts - Sidebar search filter for large APIs - Source links to GitHub for every item - Copy-to-clipboard for code blocks - Responsive, mobile-friendly layout - Page tags and tag index pages - Page status badges (experimental, stable, deprecated) - API evolution annotations (new, changed, deprecated) - Social cards (Open Graph / Twitter) - Keyboard navigation with shortcut overlay - Back-to-top floating button - Navigation icons (Lucide icon set) - Scale-to-fit for wide HTML output |
| **AI & LLM Integration** - Auto-generates `llms.txt` and `llms-full.txt` - Agent Skills generation ([agentskills.io](https://agentskills.io/) compliant) - Multiple named skills per package - Skill install/check/list CLI commands - Markdown page generation for LLM consumption - MCP server reference pages (tools, resources, prompts) | **Configuration & Branding** - Announcement banners (dismissible, styled) - Logo with light/dark variants - Custom favicon and Open Graph images - Author metadata with ORCID support - Changelog from GitHub Releases - Internationalization (20+ languages) - Accent color (global or per-mode) - Navbar gradient presets or solid colors - Content area gradient presets |
| **Quality & Reliability** - Built-in link checker - Documentation linter (docstrings, cross-refs, style) - Proofreading (spelling & grammar) - SEO auditing (sitemap, robots.txt, canonical URLs, structured data) - API diff between versions - Build timings reporting - Tested against 300+ synthetic packages via the [Great Docs Gauntlet](https://posit-dev.github.io/gdg/) - 26,000+ tests | **Deployment** - One-command GitHub Pages setup - GitHub Actions workflow generation - Multi-version deployment with version selector - Floating version aliases (`/v/latest/`, `/v/stable/`, `/v/dev/`) - Custom domain support - Static output: host anywhere |
| **Shortcodes & Widgets** - Color swatches (inline and grid) - Lightbox (zoom, galleries, annotations, before/after compare) - Terminal recordings (record, edit, embed, export as animated SVG, GIF, MP4, WebM, asciicast, or a single-file bundle, screenshot, transcripts) - Collapsible details sections - Keyboard keys styling - Horizontal rules with accent colors - Table previews (Python API for notebooks) - Table explorer (interactive data tables) | **Developer Experience** - `great-docs init` auto-detects package manager (uv, poetry, pip) - `great-docs freeze` for caching expensive computations - `great-docs timings` for build performance insight - Pre-render script hooks - Page metadata timestamps (creation/modification dates) |
Built by Posit, PBC.