Metadata-Version: 2.4
Name: great-docs
Version: 0.12.0
Summary: An easy-to-use documentation site generator for Python packages
Author-email: Rich Iannone <riannone@me.com>
Maintainer-email: Rich Iannone <riannone@me.com>
License: MIT License
        
        Copyright (c) 2026 Posit Software, PBC
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/posit-dev/great-docs
Project-URL: Repository, https://github.com/posit-dev/great-docs
Project-URL: Documentation, https://posit-dev.github.io/great-docs/
Project-URL: Bug Tracker, https://github.com/posit-dev/great-docs/issues
Keywords: documentation,documentation-generator,api-documentation,quarto,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jupyter>=1.1.1
Requires-Dist: py-yaml12>=0.1.0
Requires-Dist: click>=8.0.0
Requires-Dist: griffe<2.0.0,>=0.35.0
Requires-Dist: pygments>=2.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: ruff>=0.9.9
Provides-Extra: svg
Requires-Dist: cairosvg>=2.5.0; extra == "svg"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: ruff>=0.9.9; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pyright>=1.1.407; extra == "dev"
Requires-Dist: build>=0.7; extra == "dev"
Requires-Dist: twine>=3.4; extra == "dev"
Requires-Dist: great_tables>=0.21.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: polars>=0.20; extra == "dev"
Requires-Dist: pyarrow>=12.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: jupyter>=1.0.0; extra == "docs"
Requires-Dist: plotnine>=0.13.0; extra == "docs"
Dynamic: license-file

<p align="center">
<a href="https://posit-dev.github.io/great-docs/">
<img src="https://posit-dev.github.io/great-docs/assets/logo.svg" alt="Great Docs" width="350">
</a>
</p>
<p align="center">Documentation sites for Python packages: start simple, go deep</p>
<p align="center">
<a href="https://pypi.org/project/great-docs/"><img src="https://img.shields.io/pypi/v/great-docs?logo=python&logoColor=white&color=orange" alt="PyPI"></a>
<a href="https://pypi.org/project/great-docs/"><img src="https://img.shields.io/pypi/pyversions/great-docs.svg" alt="Python versions"></a>
<a href="https://pypistats.org/packages/great-docs"><img src="https://img.shields.io/pypi/dm/great-docs" alt="Downloads"></a>
<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
<a href="https://github.com/posit-dev/great-docs/actions/workflows/test.yml"><img src="https://github.com/posit-dev/great-docs/actions/workflows/test.yml/badge.svg?branch=main" alt="CI"></a>
</p>

---

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.

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/great-docs-site.png" alt="A documentation site generated by Great Docs" width="720">
</p>

## 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, keyboard navigation
- **Deep when you need it**: user guides, multi-version docs, freeze caching, link checking, proofreading, SEO, internationalization (20+ languages), and more (all opt-in)
- **AI-ready**: auto-generates `llms.txt`, agent skills, and markdown pages for LLM consumption
- **Deploys anywhere**: one command creates a GitHub Actions workflow for GitHub Pages

## Get Started in 60 Seconds

### Install

```bash
pip install great-docs
```

### Initialize, build, and preview

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

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/api-reference-index.png" alt="API reference index with categorized sections" width="720">
</p>

<details>
<summary>See more: class page and method page</summary>
<br>
<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/class-page.png" alt="A class documentation page with parameters and methods" width="720">
</p>
<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/method-page.png" alt="A method documentation page with signature and examples" width="720">
</p>
</details>

### CLI Reference

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

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/cli-page.png" alt="CLI reference page with terminal-style help output" width="720">
</p>

### Dark Mode

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

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/dark-mode.png" alt="Documentation site in dark mode" width="720">
</p>

## Full Feature Set

<table>
<tr>
<td width="50%" valign="top">

**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)
- Mermaid diagram pre-rendering (light + dark variants)
- Freeze/cache support for expensive computations

</td>
<td width="50%" valign="top">

**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)
- Keyboard navigation with shortcut overlay
- Back-to-top floating button
- Navigation icons (Lucide icon set)
- Scale-to-fit for wide HTML output

</td>
</tr>
<tr>
<td width="50%" valign="top">

**AI & LLM Integration**

- Auto-generates `llms.txt` and `llms-full.txt`
- Agent Skills generation ([agentskills.io](https://agentskills.io/) compliant)
- Multiple named skills per package
- Skill install/check/list CLI commands
- Markdown page generation for LLM consumption

</td>
<td width="50%" valign="top">

**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 (20+ languages)
- Accent color (global or per-mode)
- Navbar gradient presets or solid colors
- Content area gradient presets

</td>
</tr>
<tr>
<td width="50%" valign="top">

**Quality & Reliability**

- Built-in link checker
- Documentation linter (docstrings, cross-refs, style)
- Proofreading (spelling & grammar)
- SEO auditing (sitemap, robots.txt, canonical URLs, structured data)
- API diff between versions
- Build timings reporting
- Tested against ~300 synthetic packages via the [Great Docs Gauntlet](https://posit-dev.github.io/gdg/)
- 15,600+ tests

</td>
<td width="50%" valign="top">

**Deployment**

- One-command GitHub Pages setup
- GitHub Actions workflow generation
- Multi-version deployment with version selector
- Floating version aliases (`/v/latest/`, `/v/stable/`, `/v/dev/`)
- Custom domain support
- Static output: host anywhere

</td>
</tr>
<tr>
<td width="50%" valign="top">

**Shortcodes & Widgets**

- Color swatches (inline and grid)
- Terminal recordings (record, edit, embed)
- Collapsible details sections
- Keyboard keys styling
- Horizontal rules with accent colors
- Table previews (Python API for notebooks)
- Table explorer (interactive data tables)

</td>
<td width="50%" valign="top">

**Developer Experience**

- `great-docs init` auto-detects package manager (uv, poetry, pip)
- `great-docs freeze` for caching expensive computations
- `great-docs timings` for build performance insight
- Pre-render script hooks
- Page metadata timestamps (creation/modification dates)

</td>
</tr>
</table>

## 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:

```yaml
# Theming
navbar_style: sky
content_style: lilac
dark_mode_toggle: true
accent_color: "#3b82f6"

# 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"

# Freeze cache for expensive computations
freeze: auto

# Internationalization
site:
  language: fr

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

```html
---
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](https://posit-dev.github.io/great-docs/user-guide/configuration.html) for the full reference.

## Deploying to GitHub Pages

```bash
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 freeze` | Execute specific pages and persist their freeze cache |
| `great-docs timings` | Show page-level build timings from the last build |
| `great-docs setup-github-pages` | Create CI workflow for GitHub Pages deployment |
| `great-docs config` | Generate a fully-documented config template |
| `great-docs uninstall` | Remove great-docs from your project |
| `great-docs skill install` | Install AI agent skills for your package |
| `great-docs skill check` | Check if installed skills are up to date |
| `great-docs skill list` | List available skills from a package or URL |
| `great-docs termshow record` | Record a terminal session as a `.termshow` file |
| `great-docs termshow edit` | Open the browser-based visual editor for a recording |
| `great-docs termshow play` | Preview a recording in the terminal |
| `great-docs termshow render` | Render SVG frames without a full site build |
| `great-docs termshow import-cast` | Import an asciinema `.cast` file |

## Recipes

The documentation includes 24 step-by-step recipes:

### Content & API

| Recipe                                                                                                       | Topic                                      |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Hide Internal Symbols](https://posit-dev.github.io/great-docs/recipes/hide-internal-symbols.html)           | Control what appears in your API reference |
| [Customize API Organization](https://posit-dev.github.io/great-docs/recipes/customize-api-organization.html) | Structure reference sections your way      |
| [Document a CLI](https://posit-dev.github.io/great-docs/recipes/document-a-cli.html)                         | Auto-generate CLI reference from Click     |
| [Cross-Reference Items](https://posit-dev.github.io/great-docs/recipes/cross-reference-items.html)           | Link between documented objects            |
| [Write Effective Docstrings](https://posit-dev.github.io/great-docs/recipes/write-effective-docstrings.html) | Get the most out of auto-generated docs    |
| [Add Images & Diagrams](https://posit-dev.github.io/great-docs/recipes/add-images-diagrams.html)             | Include visuals in your documentation      |
| [Embed Videos](https://posit-dev.github.io/great-docs/recipes/embed-videos.html)                             | Add YouTube, Vimeo, and local videos       |

### Theming & Appearance

| Recipe                                                                                                             | Topic                                      |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Add Custom CSS](https://posit-dev.github.io/great-docs/recipes/add-custom-css.html)                               | Override styles with your own SCSS         |
| [Choose Gradient Theme](https://posit-dev.github.io/great-docs/recipes/choose-gradient-theme.html)                 | Pick and customize navbar gradients        |
| [Add Logo & Favicon](https://posit-dev.github.io/great-docs/recipes/add-logo-favicon.html)                         | Brand your site with custom icons          |
| [Customize Announcement Banner](https://posit-dev.github.io/great-docs/recipes/customize-announcement-banner.html) | Add dismissible site-wide notices          |

### Publishing & Versioning

| Recipe                                                                                                             | Topic                                      |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Create Changelog](https://posit-dev.github.io/great-docs/recipes/create-changelog.html)                           | Pull changelog from GitHub Releases        |
| [GitHub Pages & CI](https://posit-dev.github.io/great-docs/recipes/github-pages-ci.html)                           | Automate deployment with Actions           |
| [Add Custom Domain](https://posit-dev.github.io/great-docs/recipes/add-custom-domain.html)                         | Serve docs from your own domain            |
| [Enable Multi-Version Docs](https://posit-dev.github.io/great-docs/recipes/enable-multi-version-docs.html)         | Add a version selector to your site        |
| [Use Version Fences and Badges](https://posit-dev.github.io/great-docs/recipes/use-version-fences-and-badges.html) | Annotate version-specific content          |

### AI-Assisted Workflows

| Recipe                                                                                                   | Topic                                      |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [Install Great Docs Skill](https://posit-dev.github.io/great-docs/recipes/install-great-docs-skill.html) | Generate an Agent Skill for your package   |
| [Build Site with LLM](https://posit-dev.github.io/great-docs/recipes/build-site-with-llm.html)           | Use an AI assistant to set up your site    |
| [Customize Site with LLM](https://posit-dev.github.io/great-docs/recipes/customize-site-with-llm.html)   | Use an AI assistant to tweak your site     |
| [Understand llms.txt](https://posit-dev.github.io/great-docs/recipes/understand-llms-txt.html)           | Make your docs AI-accessible               |

### Build & Quality

| Recipe                                                                                                 | Topic                                      |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Fix Common Build Errors](https://posit-dev.github.io/great-docs/recipes/fix-common-build-errors.html) | Troubleshoot build issues quickly          |
| [Proofread Documentation](https://posit-dev.github.io/great-docs/recipes/proofread-documentation.html) | Catch spelling and grammar issues          |
| [Use Freeze Cache](https://posit-dev.github.io/great-docs/recipes/use-freeze-cache.html)               | Cache expensive notebooks across builds    |

## Documentation

Full documentation is available at **[posit-dev.github.io/great-docs](https://posit-dev.github.io/great-docs/)**:

- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html): setup and requirements
- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html): first site in minutes
- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html): every option explained
- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html): how API references are generated
- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html): documenting Click CLIs
- [User Guides](https://posit-dev.github.io/great-docs/user-guide/user-guides.html): adding prose documentation
- [Custom Sections](https://posit-dev.github.io/great-docs/user-guide/custom-sections.html): recipes, blog, tutorials
- [Custom Pages](https://posit-dev.github.io/great-docs/user-guide/custom-pages.html): static HTML pages
- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html): gradients, colors, dark mode
- [Diagrams](https://posit-dev.github.io/great-docs/user-guide/diagrams.html): Mermaid diagram pre-rendering
- [Videos](https://posit-dev.github.io/great-docs/user-guide/videos.html): embedding YouTube, Vimeo, and local videos
- [Internationalization](https://posit-dev.github.io/great-docs/user-guide/internationalization.html): 20+ language translations
- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html): GitHub Pages and beyond
- [Multi-Version Docs](https://posit-dev.github.io/great-docs/user-guide/multi-version-docs.html): version selector and versioned builds
- [API Evolution](https://posit-dev.github.io/great-docs/user-guide/api-evolution.html): tracking API changes across versions
- [Freeze](https://posit-dev.github.io/great-docs/user-guide/freeze.html): caching expensive computations
- [Scale to Fit](https://posit-dev.github.io/great-docs/user-guide/scale-to-fit.html): auto-shrink wide output
- [Page Tags](https://posit-dev.github.io/great-docs/user-guide/page-tags.html): categorize pages with tags
- [Page Status Badges](https://posit-dev.github.io/great-docs/user-guide/page-status-badges.html): lifecycle indicators
- [Social Cards](https://posit-dev.github.io/great-docs/user-guide/social-cards.html): Open Graph and Twitter cards
- [Agent Skills](https://posit-dev.github.io/great-docs/user-guide/agent-skills.html): AI coding agent integration
- [Link Checker](https://posit-dev.github.io/great-docs/user-guide/link-checker.html): validate all links
- [Proofreading](https://posit-dev.github.io/great-docs/user-guide/proofreading.html): spelling & grammar checks
- [Linting](https://posit-dev.github.io/great-docs/user-guide/linting.html): documentation quality checks
- [SEO](https://posit-dev.github.io/great-docs/user-guide/seo.html): search engine optimization
- [Terminal Recordings](https://posit-dev.github.io/great-docs/user-guide/terminal-recordings.html): record, edit, and embed terminal sessions

## Requirements

- **Python 3.11+**
- **[Quarto](https://quarto.org/docs/get-started/)** (the rendering engine)

## Contributing

Contributions are welcome! Please see [CONTRIBUTING](https://posit-dev.github.io/great-docs/contributing.html) for guidelines and the [Code of Conduct](https://posit-dev.github.io/great-docs/code-of-conduct.html).

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<p align="center">
Built by <a href="https://posit.co">Posit, PBC</a>.
</p>
