great-docs 0.3

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

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.

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 it handles the rest.

• Instant setup: great-docs init inspects 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

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.)	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
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
Quality & Reliability Built-in link checker Proofreading (spelling & grammar) Tested against 250+ synthetic packages 6,500+ unit tests	Deployment One-command GitHub Pages setup GitHub Actions workflow generation 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

# Custom sections
sections:
  - title: Recipes
    dir: recipes
    navbar_after: User Guide

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.

Recipes

The documentation includes 18 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
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
Write Effective Docstrings	Get the most out of auto-generated docs
Add Images & Diagrams	Include visuals in your documentation
Create Changelog	Pull changelog from GitHub Releases
GitHub Pages & CI	Automate deployment with Actions
Add Custom Domain	Serve docs from your own domain
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
Fix Common Build Errors	Troubleshoot build issues quickly

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

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