![Logo](assets/logo.svg) ![Logo](assets/logo-dark.svg) 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 ``` console $ python ../../scripts/make_landing_demo_pkg.py /tmp/weathervault && cd /tmp && export PYTHONPATH=/tmp/weathervault && clear ``` **Initialize** ``` console $ 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 rebuild ``` **Build** ``` console $ 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** ``` console $ 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](https://modelcontextprotocol.io/). 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 ``` bash great-docs setup-github-pages ``` Creates a GitHub Actions workflow. Every push to `main` rebuilds and publishes your site automatically. ### Go Further [📖 User Guide Installation, configuration, theming, multi-version docs, and deployment. →](user-guide/installation.md) [🍳 Recipes Bite-sized guides for specific tasks: copy, paste, done. →](recipes/hide-internal-symbols.md) [⚙️ API Reference Great Docs documenting itself (every class, function, and option). →](reference/index.md) ## There's Always More to Explore. Auto-Generated API Ref­er­ence • Dark Mode Toggle • llms.txt & Agent Skills • Multi-Version Docu­men­ta­tion • GitHub Pages in One Com­mand • Click CLI Docu­men­ta­tion • Animated Term­show Re­cord­ings • Term­show Visual Editor • Animated Gradient Nav­bars & Ban­ners • Three Com­mands to Launch • Change­log from GitHub Re­leases • Hero Section Support • Rich Table Pre­views for Pandas, Polars & Arrow • Full-Screen Light­box with Zoom & Gal­ler­ies Numpy, Google & Sphinx Doc­strings • Version Selector Widget • **Side­bar Search & Fil­ter­ing** • Page Tags & Status Badges • Mer­maid Dia­gram Ren­der­ing • Inter­active Table Ex­plor­er • Docu­men­ta­tion Linter • Spelling & Grammar Check­ing • Twenty-Three Lan­guages • Key­board Navi­ga­tion • Custom Sections & Recipes • Respon­sive on Every Screen • **GitHub Star Count Widget** • SEO Audit & Site­map Gen­er­a­tion • Announce­ment Ban­ners • Auto-Detected Logos with Dark-Mode Vari­ants • API Diff Between Ver­sions • Tool­tips & Pop­overs • **Rich Meta­data Side­bar with De­vel­oper Links** • Code Auto­links in Doc­strings • Sub­mod­ule Intro­spec­tion • Copy & View Page as Mark­down  **APCA Contrast Algo­rithm** • Fav­icon Auto-Gen­er­a­tion • Scale-to-Fit Wide Tables • Copy Code Buttons • Syn­tax High­light­ing & Exe­cut­able Code Blocks • In­line Icons • Version Fences & Badges • Breaking Change Detec­tion • API Sur­face Time­line • Param­eter Evo­lu­tion Tables • JSON-LD Struc­tured Data • Canon­ical URLs • Social Cards & Open Graph • Source Links to GitHub • **1,941 Bundled Lucide Icons** • Commu­nity File Pages • **SPDX License Data­base** • PR Pre­view Deploy­ments • Custom SCSS Theming • Blog Sup­port • Cross-Refs, %see­also & In­line Inter­links • Video Embeds • Color Swatches • Image Anno­ta­tions & Before/After Com­pare • FastMCP Server Detec­tion • Tab­sets & Cal­louts • Link Checker • Config Gen­er­a­tion • Robots.txt & Crawl Rules • Non-Breaking Re­build Mode • API Snap­shots to JSON • Custom Static Pages • Object-Type Label Colors • **Styled Sig­na­tures & Type Anno­ta­tions** • Meth­od Mem­ber Con­trol & Ex­clude Lists • Nav­bar & Side­bar Icons • Verbose Build Log­ging • Custom Head In­jec­tion for Scripts & Meta • **Back-to-Top Button** • ...and Yes, It Builds *Fast* × ### [Learn more →](#) ------------------------------------------------------------------------ Something missing? [Open an issue](https://github.com/posit-dev/great-docs/issues).