Great Docs
Documentation sites for Python packages. Three commands. Zero friction.
Give your Python package the documentation site it deserves. Great Docs turns your docstrings, README, and CLI into a polished documentation site. When you’re ready to go further, there’s a world of features waiting. Start simple, go deep.
Three Commands. One Beautiful Site.
Transcript of the terminal recording: landing-demo
$ python ../../scripts/make_landing_demo_pkg.py /tmp/weathervault && cd /tmp &&
export PYTHONPATH=/tmp/weathervault && clearInitialize
$ cd weathervault
$ great-docs init
Initializing great-docs...
Detecting docstring style...
Docstring style detection: numpy=12, google=0, sphinx=0
Detected numpy docstring style
Using __all__ with 12 exports
Categorizing API objects...
Forecast: class with 2 public methods
Observation: class with 0 public methods
Station: class with 1 public methods
Testing dynamic introspection mode...
Dynamic introspection mode works for this package
Created /private/tmp/weathervault/docs/great-docs.yml
Ignore Great Docs build output? [Y/n]: y
✅ 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 rebuildBuild
$ great-docs build
┌────────────────────────────────────────────────────────────────────────────┐
│ great-docs build · weathervault │
│ from /private/tmp/weathervault/weathervault │
│ 20 steps · estimated ~1 min │
└────────────────────────────────────────────────────────────────────────────┘
━━ Step 1/20 ─ Prepare build directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Preparing build directory: docs/_quarto/default/
Updated /private/tmp/weathervault/docs/_quarto/default/_quarto.yml with gr
eat-docs configuration
Adding API reference configuration for package: weathervault
Using explicit reference configuration from great-docs.yml
Generated 2 section(s) from reference config
Using 'python3' Jupyter kernel
Auto-generated 2 section(s) from package exports
Added API reference configuration to /private/tmp/weathervault/docs/_quart
o/default/_quarto.yml
Created /private/tmp/weathervault/docs/_quarto/default/package-info.qmd
Rebuilding index.qmd from README.md...
Created /private/tmp/weathervault/docs/_quarto/default/index.qmd
✔ Ready 0.2s
Freeze mode: auto
━━ Step 2/20 ─ Configure API reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
API reference already configured in this build, skipping re-discovery
✔ API reference refreshed <0.1s
━━ Step 3/20 ─ Generate llms.txt / llms-full.txt ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Created /private/tmp/weathervault/docs/_quarto/default/llms.txt
Created /private/tmp/weathervault/docs/_quarto/default/llms-full.txt
✔ Created llms.txt + llms-full.txt <0.1s
━━ Step 4/20 ─ Generate SKILL.md ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Created /private/tmp/weathervault/docs/_quarto/default/skill.md
✔ Created skill.md <0.1s
━━ Step 5/20 ─ Generate changelog ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (no GitHub repo info)
━━ Step 6/20 ─ Generate CLI reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (CLI not enabled)
━━ Step 7/20 ─ Generate Go CLI reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (Go CLI not enabled)
━━ Step 8/20 ─ Generate Rust CLI reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (Rust CLI not enabled)
━━ Step 9/20 ─ Generate MCP server reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
No MCP module configured or found
⊘ Skipped (no MCP server found)
━━ Step 10/20 ─ Process User Guide ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Processing User Guide...
Found 3 page(s)
Copied 3 file(s) to docs/user-guide/
User Guide configured
✔ User Guide configured <0.1s
━━ Step 11/20 ─ Process custom sections ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (no sections configured)
━━ Step 12/20 ─ Process custom pages ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Custom pages directory 'custom' not found, skipping
⊘ Skipped (no custom pages)
━━ Step 13/20 ─ Process page tags ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (tags not enabled)
━━ Step 14/20 ─ Process page status badges ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (page status not enabled)
━━ Step 15/20 ─ Copy assets ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Updated /private/tmp/weathervault/docs/_quarto/default/_quarto.yml with gr
eat-docs configuration
⊘ Skipped (no assets directory)
━━ Step 16/20 ─ Generate API reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✔ API reference generated <0.1s
━━ Step 17/20 ─ Build interlinks index ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✔ Indexed 48 name(s) <0.1s
━━ Step 18/20 ─ Prepare freeze cache ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⊘ Skipped (no frozen pages)
Sharing rendered sidebar(s): reference
━━ Step 19/20 ─ Build site with Quarto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✔ Site rendered 7.5s
━━ Step 20/20 ─ Generate SEO files ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generating SEO files...
No base URL configured, skipping sitemap generation
Set seo.canonical.base_url in great-docs.yml or configure a GitHub r
epo
Generated robots.txt
✔ sitemap.xml + robots.txt <0.1s
Wrote build-timings.json
┌────────────────────────────────────────────────────────────────────────────┐
│ ✔ Build complete — 20/20 steps (11 skipped) │
│ Total time: 7.8s │
│ │
│ 🎉 Site ready → /private/tmp/weathervault/docs/_site/index.html │
└────────────────────────────────────────────────────────────────────────────┘Preview
$ great-docs preview
Previewing documentation...
🌐 Serving site at http://localhost:3000/
Press Ctrl+C to stop
^C$That’s it. Your API reference, CLI docs, and landing page are ready to go. Push to GitHub and you’re live.
Your Docstrings, Finally Doing Their Job
Every class, function, method, and attribute in your public API gets its own structured page with parameter tables, return types, source links, and rendered examples. Numpy, Google, and Sphinx docstring styles all work out of the box.
If your package has a Click CLI, that’s documented as well (complete with terminal-style help output and subcommand trees).
Want to show your CLI in action? Termshow lets you record terminal sessions, edit them visually in a browser-based editor, and embed the results as animated SVG players directly in your documentation. No screen recordings, no GIFs, no JavaScript… just lightweight, theme-aware terminal playback that lives alongside your reference pages.
Looks Good Without Trying
Dark mode with a persistent toggle. Responsive on every screen. Sidebar search for large APIs. GitHub star counts in the corner. Screenshots and diagrams expand into a full-screen lightbox with zoom, galleries, annotations, and before/after comparison.
With a line or two of configuration you can add animated gradient navbars, announcement banners, custom logos, and more.
Your package gets a site that matches the quality of the code behind it.
AI-Native from Day One
Great Docs generates llms.txt and llms-full.txt so AI coding agents can understand your library without scraping HTML. It also produces Agent Skills files: structured metadata that tells tools like Copilot, Cursor, and Claude Code how to use your package (not just what it exports).
If your package ships an MCP server, Great Docs auto-generates reference pages for every tool, resource, and prompt it exposes, giving agents structured documentation they can discover through the Model Context Protocol.
You can also write your own custom skills and publish them with your site. Your users install them with a single command.
Deploy in One Step
great-docs setup-github-pagesCreates a GitHub Actions workflow. Every push to main rebuilds and publishes your site automatically.
Go Further
There's Always More to Explore.
Auto-Generated API Reference • Dark Mode Toggle • llms.txt & Agent Skills • Multi-Version Documentation • GitHub Pages in One Command • Click CLI Documentation • Animated Termshow Recordings • Termshow Visual Editor • Animated Gradient Navbars & Banners • Three Commands to Launch • Changelog from GitHub Releases • Hero Section Support • Rich Table Previews for Pandas, Polars & Arrow • Full-Screen Lightbox with Zoom & Galleries
Numpy, Google & Sphinx Docstrings • Version Selector Widget • Sidebar Search & Filtering • Page Tags & Status Badges • Mermaid Diagram Rendering • Interactive Table Explorer • Documentation Linter • Spelling & Grammar Checking • Twenty-Three Languages • Keyboard Navigation • Custom Sections & Recipes • Responsive on Every Screen • GitHub Star Count Widget • SEO Audit & Sitemap Generation • Announcement Banners • Auto-Detected Logos with Dark-Mode Variants • API Diff Between Versions • Tooltips & Popovers • Rich Metadata Sidebar with Developer Links • Code Autolinks in Docstrings • Submodule Introspection • Copy & View Page as Markdown
APCA Contrast Algorithm • Favicon Auto-Generation • Scale-to-Fit Wide Tables • Copy Code Buttons • Syntax Highlighting & Executable Code Blocks • Inline Icons • Version Fences & Badges • Breaking Change Detection • API Surface Timeline • Parameter Evolution Tables • JSON-LD Structured Data • Canonical URLs • Social Cards & Open Graph • Source Links to GitHub • 1,941 Bundled Lucide Icons • Community File Pages • SPDX License Database • PR Preview Deployments • Custom SCSS Theming • Blog Support • Cross-Refs, %seealso & Inline Interlinks • Video Embeds • Color Swatches • Image Annotations & Before/After Compare • FastMCP Server Detection • Tabsets & Callouts • Link Checker • Config Generation • Robots.txt & Crawl Rules • Non-Breaking Rebuild Mode • API Snapshots to JSON • Custom Static Pages • Object-Type Label Colors • Styled Signatures & Type Annotations • Method Member Control & Exclude Lists • Navbar & Sidebar Icons • Verbose Build Logging • Custom Head Injection for Scripts & Meta • Back-to-Top Button • ...and Yes, It Builds Fast
Something missing? Open an issue.