Metadata-Version: 2.4
Name: great-docs
Version: 0.3
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: cairosvg>=2.5.0
Requires-Dist: ruff>=0.9.9
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"
Provides-Extra: docs
Requires-Dist: jupyter>=1.0.0; extra == "docs"
Dynamic: license-file

<p align="center">
<a href="https://posit-dev.github.io/great-docs/">
<img src="assets/logo.svg" alt="Great Docs" width="350">
</a>
</p>
<p align="center">An easy-to-use documentation site generator for Python packages</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 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.

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

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

</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

</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)
- 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

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

**Quality & Reliability**

- Built-in link checker
- Proofreading (spelling & grammar)
- Tested against 250+ synthetic packages
- 6,500+ unit tests

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

**Deployment**

- One-command GitHub Pages setup
- GitHub Actions workflow generation
- Custom domain support
- Static output: host anywhere

</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

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

## Recipes

The documentation includes 18 step-by-step recipes:

| 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            |
| [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          |
| [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      |
| [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            |
| [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               |
| [Fix Common Build Errors](https://posit-dev.github.io/great-docs/recipes/fix-common-build-errors.html)             | Troubleshoot build issues quickly          |

## 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
- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html) — gradients, colors, dark mode
- [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
- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html) — GitHub Pages and beyond

## 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</a>
</p>
