great-docs 0.10.0

An easy-to-use documentation site generator for Python packages

Documentation sites for Python packages: start simple, go deep

---

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.

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
• Deep when you need it: user guides, multi-version docs, link checking, proofreading, SEO, internationalization, and more (all opt-in)
• Deploys anywhere: one command creates a GitHub Actions workflow for GitHub Pages

Get Started in 60 Seconds

Install

pip install great-docs

Initialize, build, and preview

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.

See more: class page and method page

CLI Reference

Click-based CLIs are documented automatically with --help output rendered in terminal style, organized by command group.

Dark Mode

A persistent dark mode toggle with flash-free loading. Your users' preference is remembered across visits.

Full Feature Set

Documentation Generation Auto-discovers exports via __all__, dir(), or static analysis Detects NumPy, Google, and Sphinx docstring formats 13 object types with smart categorization Click CLI documentation User Guide pages from 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)	Site Features Dark mode toggle with persistent preference 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)
AI & LLM Integration Auto-generates llms.txt and llms-full.txt Agent Skills generation (agentskills.io compliant) Markdown page generation for LLM consumption	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 support
Quality & Reliability Built-in link checker Documentation linter (docstrings, cross-refs, style) Proofreading (spelling & grammar) SEO auditing API diff between versions Tested against 250+ synthetic packages 15,600+ tests	Deployment One-command GitHub Pages setup GitHub Actions workflow generation Multi-version deployment with version selector Custom domain support Static output: host anywhere

Configuration

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 Guide

Custom 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.

Deploying to GitHub Pages

great-docs setup-github-pages

This 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.

CLI Commands

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

Recipes

The documentation includes 22 step-by-step recipes:

Content & API

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

Theming & Appearance

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

Publishing & Versioning

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

AI-Assisted Workflows

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

Build & Quality

Recipe	Topic
Fix Common Build Errors	Troubleshoot build issues quickly
Proofread Documentation	Catch spelling and grammar issues

Documentation

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

Requirements

• Python 3.11+
• Quarto (the rendering engine)

Contributing

Contributions are welcome! Please see CONTRIBUTING for guidelines and the Code of Conduct.

License

MIT License. See LICENSE for details.

---

Built by Posit