# 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](https://quarto.org/), 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](https://quarto.org/docs/get-started/) 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](https://posit-dev.github.io/great-docs/user-guide/user-guides.html) in Quarto Markdown, including nested sections. Compare it with other documentation generators in [Which Python documentation tool should I use?](https://pydevtools.com/handbook/explanation/which-python-documentation-tool-should-i-use.md).

Prefer [Zensical](https://zensical.org/) or [MkDocs](https://pydevtools.com/handbook/reference/mkdocs.md) when prose is the main content. Choose [Sphinx](https://pydevtools.com/handbook/reference/sphinx.md) 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:

```bash
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:

```bash
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](https://posit-dev.github.io/great-docs/user-guide/installation.html) alongside the Python `great-docs` package. This is a meaningful difference from [Sphinx](https://pydevtools.com/handbook/reference/sphinx.md) and [MkDocs](https://pydevtools.com/handbook/reference/mkdocs.md), 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](https://github.com/quarto-dev/quarto-actions) 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
