An easy-to-use documentation site generator for Python packages
Great Docs turns your Python package into a polished documentation site in seconds. It auto-discovers your public API, detects your docstring format, generates structured reference pages, and renders a modern site: all from a single command. No templates to configure, no manual page authoring, no build system to learn.
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 it handles the rest.
- Instant setup:
great-docs initinspects your package and generates a complete config - Zero manual authoring: API reference pages are created automatically from your code
- 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
- Deploys anywhere: one command creates a GitHub Actions workflow for GitHub Pages
pip install great-docscd 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:3000That's it. Your documentation site is ready.
Every site built by Great Docs includes:
Your README is transformed into a landing page with a hero section, metadata sidebar (authors, license, links), and quick-start instructions.
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.
See more: class page and method page
Click-based CLIs are documented automatically with --help output rendered in terminal style, organized by command group.
A persistent dark mode toggle with flash-free loading. Your users' preference is remembered across visits.
|
Documentation Generation
|
Site Features
|
|
AI & LLM Integration
|
Configuration & Branding
|
|
Quality & Reliability
|
Deployment
|
All configuration lives in a single great-docs.yml file in your project root. The init command generates it for you, but you can customize everything:
# Theming
navbar_style: sky
content_style: lilac
dark_mode_toggle: true
# Branding
display_name: My Package
logo:
light: assets/logo.svg
dark: assets/logo-dark.svg
# Announcement banner
announcement:
content: "v2.0 is here!"
style: mint
dismissable: true
# GitHub integration
repo: https://github.com/your-org/your-package # Optional override
github_style: widget
# CLI documentation
cli:
enabled: true
module: my_package.cli
name: cli
# Multi-version documentation
versions:
- tag: v2.0.0
label: "2.0 (latest)"
- tag: v1.5.0
label: "1.5"
# Custom sections
sections:
- title: Recipes
dir: recipes
navbar_after: User GuideCustom HTML pages can live in a custom/ directory and are discovered automatically during build.
---
title: Landing Page
layout: passthrough
navbar: true
---
<section class="hero">...</section>Use layout: passthrough to wrap the HTML body with the normal Great Docs shell, or layout: raw to copy the HTML file through unchanged.
Set navbar: true to add the page to the site navbar using its title, or use navbar: {text: Showcase, after: Guide} for explicit navbar label and placement.
See the Configuration Guide for the full reference.
great-docs setup-github-pagesThis creates a .github/workflows/ file that builds and publishes your site on every push to main. Your docs stay in sync with your code automatically.
Beyond init, build, and preview, Great Docs includes a full suite of quality and maintenance tools:
| Command | Purpose |
|---|---|
great-docs scan |
Preview discovered exports before building |
great-docs lint |
Check for missing docstrings, broken cross-refs, style issues |
great-docs proofread |
Catch spelling and grammar problems |
great-docs check-links |
Validate all links in the built site |
great-docs seo |
Audit SEO health (sitemap, meta tags, structured data) |
great-docs api-diff OLD NEW |
Show API changes between two versions |
great-docs api-snapshot |
Capture a JSON snapshot of your public API |
great-docs versions |
List and validate multi-version configuration |
great-docs changelog |
Generate changelog from GitHub Releases |
great-docs setup-github-pages |
Create CI workflow for GitHub Pages deployment |
great-docs config |
Generate a fully-documented config template |
The documentation includes 22 step-by-step recipes:
| Recipe | Topic |
|---|---|
| Hide Internal Symbols | Control what appears in your API reference |
| Customize API Organization | Structure reference sections your way |
| Document a CLI | Auto-generate CLI reference from Click |
| Cross-Reference Items | Link between documented objects |
| Write Effective Docstrings | Get the most out of auto-generated docs |
| Add Images & Diagrams | Include visuals in your documentation |
| Embed Videos | Add YouTube, Vimeo, and local videos |
| Recipe | Topic |
|---|---|
| Add Custom CSS | Override styles with your own SCSS |
| Choose Gradient Theme | Pick and customize navbar gradients |
| Add Logo & Favicon | Brand your site with custom icons |
| Customize Announcement Banner | Add dismissible site-wide notices |
| Recipe | Topic |
|---|---|
| Create Changelog | Pull changelog from GitHub Releases |
| GitHub Pages & CI | Automate deployment with Actions |
| Add Custom Domain | Serve docs from your own domain |
| Enable Multi-Version Docs | Add a version selector to your site |
| Use Version Fences and Badges | Annotate version-specific content |
| Recipe | Topic |
|---|---|
| Install Great Docs Skill | Generate an Agent Skill for your package |
| Build Site with LLM | Use an AI assistant to set up your site |
| Customize Site with LLM | Use an AI assistant to tweak your site |
| Understand llms.txt | Make your docs AI-accessible |
| Recipe | Topic |
|---|---|
| Fix Common Build Errors | Troubleshoot build issues quickly |
| Proofread Documentation | Catch spelling and grammar issues |
Full documentation is available at posit-dev.github.io/great-docs:
- Installation: setup and requirements
- Quick Start: first site in minutes
- Configuration: every option explained
- Theming & Appearance: gradients, colors, dark mode
- API Documentation: how API references are generated
- CLI Documentation: documenting Click CLIs
- Deployment: GitHub Pages and beyond
- Link Checker: validate all links
- Proofreading: spelling & grammar checks
- Linting: documentation quality checks
- SEO: search engine optimization
- Multi-Version Docs: version selector and versioned builds
- API Evolution: tracking API changes across versions
- Social Cards: Open Graph and Twitter cards
- Python 3.11+
- Quarto (the rendering engine)
Contributions are welcome! Please see CONTRIBUTING for guidelines and the Code of Conduct.
MIT License. See LICENSE for details.
Built by Posit