Skip to content

Great Docs: Package-First Python Documentation Generator

Great Docs is a documentation generator that scans a Python package and produces a complete site: landing page, API reference, navigation, and search. Built by Posit on Quarto, it treats the package’s public API as the primary input rather than hand-written source files.

Note

Great Docs is licensed MIT. Install with uv add --group docs great-docs or pip install great-docs. Great Docs also requires a system-level Quarto installation and Python 3.11 or later.

When to use Great Docs

Consider Great Docs when the API is the primary content and contributors can install the Quarto system dependency. It also supports authored narrative pages and user guides in Quarto Markdown, including nested sections. Compare it with other documentation generators in Which Python documentation tool should I use?.

Prefer Zensical or MkDocs when prose is the main content. Choose Sphinx when semantic cross-references across projects matter. Choose another tool when the built-in Sphinx/MkDocs workflow on Read the Docs is needed or contributors cannot install Quarto.

Key Features

  • Scans a Python package and auto-discovers public objects, docstring format, and package manager
  • Generates API reference, landing page, and navigation from the scan
  • Produces llms.txt and MCP documentation for AI tooling
  • Detects Click-based CLIs and generates CLI reference pages
  • Supports Google, NumPy, and Sphinx docstring formats (auto-detected)
  • Multi-version documentation with floating aliases (/v/latest/, /v/stable/)
  • Built-in link checker, documentation linter, and spell checker
  • Social cards (Open Graph and Twitter)
  • One-command GitHub Pages deployment via generated GitHub Actions workflow

Configuration

uv run --group docs makes the commands available after installing with uv add --group docs great-docs. From the package root, initialize the configuration:

uv run --group docs great-docs init

Initialization may ask to add the generated great-docs/ directory to .gitignore; accept to keep generated output out of version control. The configuration is saved to great-docs.yml.

Build and preview the site:

uv run --group docs great-docs build
uv run --group docs great-docs preview

The generated site opens at localhost:3000. Configuration lives in great-docs.yml at the project root; great-docs init generates sensible defaults from the package metadata.

Quarto dependency

Great Docs uses Quarto as its rendering engine. Contributors and CI environments need a Quarto installation alongside the Python great-docs package. This is a meaningful difference from Sphinx and MkDocs, whose basic HTML builds do not require Quarto. Sphinx PDF builds through LaTeX require a separate LaTeX installation.

In CI, install Quarto before the documentation build step. The Quarto setup action handles this in GitHub Actions. For Linux container builds, install the Quarto .deb on Debian or Ubuntu, or use the Linux tarball for another distribution.

Pros

  • Generates a site from package metadata and docstrings
  • Auto-discovers the public API without writing directive markup
  • llms.txt and MCP output connect the docs to AI tooling
  • CLI reference generation for Click-based applications
  • Built-in quality checks (links, spelling, linting)

Cons

  • Requires a system-level Quarto installation (not pure Python)
  • Pre-1.0: the API and configuration surface may change between releases
  • Smaller ecosystem of themes and extensions than Sphinx or MkDocs
Last updated on