Welcome to Great Docs

Great Docs is a documentation site generator for Python packages. Run one command, get a complete documentation site. Customize as much or as little as you want.

Get Up and Running Fast

Point Great Docs at your Python package and it does the rest. great-docs init scans your codebase, discovers your public API, detects your docstring format, and writes all the configuration for you. Then great-docs build produces a full documentation site (landing page, API reference, navigation) ready to preview and deploy.

No templates to author. No content pages to write by hand. No build system to learn.

Your Site Looks Great From the Start

The default site isn’t a starting point you’ll need to overhaul. It’s a polished, modern documentation site right away: dark mode, responsive layout, GitHub integration, structured parameter tables, and source links. Whether your package exposes a handful of functions or a deep class hierarchy, Great Docs figures out how to present it well.

Explore a World of Possibilities

When you’re ready for more, there’s a lot here:

• Narrative user guides and tutorials alongside your API reference
• Blogs, recipe sections, custom pages, and additional content sections
• Diagrams, videos, color swatches, and interactive table previews
• Gradient themes, announcement banners, and custom branding
• Internationalization across twenty-three languages

Every feature is opt-in. Your site stays clean until you decide to expand it.

Go as Deep as You Need

As your project grows, Great Docs keeps up. Publish multiple versions with a version selector. Track API changes across releases. Run the built-in link checker, linter, and proofreader. Generate llms.txt for AI tools. Deploy to GitHub Pages in one step.

We keep on building the tools you’ll need, and they’ll be here when the time is right for you.

What You’ll Learn

This User Guide covers everything you need to know to build and maintain great documentation sites. Here’s what to expect:

Getting started: Installing Great Docs, creating your first site, authoring .qmd files, writing effective docstrings, and understanding the project structure.

Configuration and theming: Tuning site behavior through great-docs.yml, customizing appearance, setting up cross-references, internationalization, and responsive scaling.

Site content: Auto-generated API and CLI references, narrative user guides, custom sections and static pages, blogs, diagrams, videos, tables, color swatches, and more.

Building and deployment: Previewing locally, publishing to GitHub Pages, SEO optimization, social cards, and multi-version documentation.

Quality and maintenance: Link checking, proofreading, linting, changelogs, community files, page status badges, and tracking API evolution.

Next Steps

This User Guide covers everything from first install to production deployment. Start at the beginning or jump to whatever topic you need.

• Installation gets Great Docs and Quarto set up on your machine
• Quick Start walks you through creating your first documentation site
• Authoring QMD Files teaches the Markdown, frontmatter, and Quarto features you’ll use everywhere