Skip to content

Commit 25cfb7c

Browse files
rich-iannonerich-iannone
committed
Update README.md
1 parent 5a70e92 commit 25cfb7c

File tree

1 file changed

+237
-64
lines changed

1 file changed

+237
-64
lines changed

‎README.md‎

Lines changed: 237 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,273 @@
1-
# Great Docs
1+
<p align="center">
2+
<a href="https://posit-dev.github.io/great-docs/">
3+
<img src="assets/logo.svg" alt="Great Docs" width="350">
4+
</a>
5+
</p>
6+
<p align="center">Professional documentation for Python packages. One command, zero configuration.</p>
7+
<p align="center">
8+
<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>
9+
<a href="https://pypi.org/project/great-docs/"><img src="https://img.shields.io/pypi/pyversions/great-docs.svg" alt="Python versions"></a>
10+
<a href="https://pypistats.org/packages/great-docs"><img src="https://img.shields.io/pypi/dm/great-docs" alt="Downloads"></a>
11+
<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
12+
<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>
13+
</p>
214

3-
[![Python versions](https://img.shields.io/pypi/pyversions/great-docs.svg)](https://pypi.org/project/great-docs/)
4-
[![PyPI](https://img.shields.io/pypi/v/great-docs?logo=python&logoColor=white&color=orange)](https://pypi.org/project/great-docs/)
5-
[![PyPI Downloads](https://img.shields.io/pypi/dm/great-docs)](https://pypistats.org/packages/great-docs)
6-
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
7-
[![CI Build](https://github.com/posit-dev/great-docs/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/posit-dev/great-docs/actions/workflows/test.yml)
8-
[![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
9-
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
15+
---
1016

11-
Great Docs automatically creates professional documentation with auto-generated API references, CLI documentation, smart navigation, and modern styling.
17+
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.
1218

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

15-
- **One-command setup** — `great-docs init` creates your entire docs site
16-
- **Auto-generated API docs** — discovers and documents your package's public API
17-
- **Docstring detection** — automatically detects NumPy, Google, or Sphinx style
18-
- **CLI documentation** — generates reference pages for Click-based CLIs
19-
- **Smart organization** — intelligent class/method/function categorization
20-
- **User Guide support** — write narrative documentation alongside API reference
21-
- **Source links** — automatic links to source code on GitHub
22-
- **LLM-friendly** — auto-generates `llms.txt` and `llms-full.txt` for AI documentation indexing
23-
- **GitHub Pages ready** — one command sets up deployment workflow
23+
## Why Great Docs?
2424

25-
## Quick Start
25+
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.
2626

27-
### Install
27+
- **Instant setup** — `great-docs init` inspects your package and generates a complete config
28+
- **Zero manual authoring** — API reference pages are created automatically from your code
29+
- **Real documentation, not stubs** — renders full parameter tables, return types, examples, and cross-references from your existing docstrings
30+
- **Looks great out of the box** — gradient navbars, dark mode, responsive layout, GitHub widget, sidebar search
31+
- **Deploys anywhere** — one command creates a GitHub Actions workflow for GitHub Pages
32+
33+
## Get Started in 60 Seconds
2834

29-
Great Docs is not yet available on PyPI, so, install from GitHub:
35+
### Install
3036

3137
```bash
32-
pip install git+https://github.com/posit-dev/great-docs.git
38+
pip install great-docs
3339
```
3440

35-
### Initialize
36-
37-
Navigate to your Python project and run:
41+
### Initialize, build, and preview
3842

3943
```bash
40-
great-docs init
44+
cd your-python-package
45+
46+
great-docs init # auto-detect package, generate config
47+
great-docs build # generate and render the site
48+
great-docs preview # open in your browser at localhost:3000
4149
```
4250

43-
This auto-detects your package and creates a `great-docs.yml` configuration file with your API structure.
51+
That's it. Your documentation site is ready.
4452

45-
### Build
53+
## What Gets Generated
4654

47-
```bash
48-
great-docs build
49-
```
55+
Every site built by Great Docs includes:
5056

51-
This creates the `great-docs/` directory with all assets and builds your site to `great-docs/_site/`.
57+
### Landing Page
5258

53-
### Preview
59+
Your README is transformed into a landing page with a hero section, metadata sidebar (authors, license, links), and quick-start instructions.
5460

55-
```bash
56-
great-docs preview
61+
### API Reference
62+
63+
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.
64+
65+
<p align="center">
66+
<img src="https://posit-dev.github.io/great-docs/assets/api-reference-index.png" alt="API reference index with categorized sections" width="720">
67+
</p>
68+
69+
<details>
70+
<summary>See more: class page and method page</summary>
71+
<br>
72+
<p align="center">
73+
<img src="https://posit-dev.github.io/great-docs/assets/class-page.png" alt="A class documentation page with parameters and methods" width="720">
74+
</p>
75+
<p align="center">
76+
<img src="https://posit-dev.github.io/great-docs/assets/method-page.png" alt="A method documentation page with signature and examples" width="720">
77+
</p>
78+
</details>
79+
80+
### CLI Reference
81+
82+
Click-based CLIs are documented automatically with `--help` output rendered in terminal style, organized by command group.
83+
84+
<p align="center">
85+
<img src="https://posit-dev.github.io/great-docs/assets/cli-page.png" alt="CLI reference page with terminal-style help output" width="720">
86+
</p>
87+
88+
### Dark Mode
89+
90+
A persistent dark mode toggle with flash-free loading. Your users' preference is remembered across visits.
91+
92+
<p align="center">
93+
<img src="https://posit-dev.github.io/great-docs/assets/dark-mode.png" alt="Documentation site in dark mode" width="720">
94+
</p>
95+
96+
## Full Feature Set
97+
98+
<table>
99+
<tr>
100+
<td width="50%" valign="top">
101+
102+
**Documentation Generation**
103+
104+
- Auto-discovers exports via `__all__`, `dir()`, or static analysis
105+
- Detects NumPy, Google, and Sphinx docstring formats
106+
- 13 object types with smart categorization
107+
- Click CLI documentation
108+
- User Guide pages from `user_guide/` directory
109+
- Custom sections (recipes, blog, tutorials, etc.)
110+
111+
</td>
112+
<td width="50%" valign="top">
113+
114+
**Site Features**
115+
116+
- Dark mode toggle with persistent preference
117+
- GitHub widget with live star/fork counts
118+
- Sidebar search filter for large APIs
119+
- Source links to GitHub for every item
120+
- Copy-to-clipboard for code blocks
121+
- Responsive, mobile-friendly layout
122+
123+
</td>
124+
</tr>
125+
<tr>
126+
<td width="50%" valign="top">
127+
128+
**AI & LLM Integration**
129+
130+
- Auto-generates `llms.txt` and `llms-full.txt`
131+
- Agent Skills generation ([agentskills.io](https://agentskills.io/) compliant)
132+
- Markdown page generation for LLM consumption
133+
134+
</td>
135+
<td width="50%" valign="top">
136+
137+
**Configuration & Branding**
138+
139+
- Announcement banners (dismissible, styled)
140+
- Logo with light/dark variants
141+
- Custom favicon and Open Graph images
142+
- Author metadata with ORCID support
143+
- Changelog from GitHub Releases
144+
145+
</td>
146+
</tr>
147+
<tr>
148+
<td width="50%" valign="top">
149+
150+
**Quality & Reliability**
151+
152+
- Built-in link checker
153+
- Spell checking
154+
- Tested against 215+ synthetic packages
155+
- 9,300+ unit tests
156+
157+
</td>
158+
<td width="50%" valign="top">
159+
160+
**Deployment**
161+
162+
- One-command GitHub Pages setup
163+
- GitHub Actions workflow generation
164+
- Custom domain support
165+
- Static output — host anywhere
166+
167+
</td>
168+
</tr>
169+
</table>
170+
171+
## Configuration
172+
173+
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:
174+
175+
```yaml
176+
# Theming
177+
navbar_style: sky
178+
content_style: lilac
179+
dark_mode_toggle: true
180+
181+
# Branding
182+
display_name: My Package
183+
logo:
184+
light: assets/logo.svg
185+
dark: assets/logo-dark.svg
186+
187+
# Announcement banner
188+
announcement:
189+
content: "v2.0 is here!"
190+
style: mint
191+
dismissable: true
192+
193+
# GitHub integration
194+
github_style: widget
195+
196+
# CLI documentation
197+
cli:
198+
enabled: true
199+
module: my_package.cli
200+
name: cli
201+
202+
# Custom sections
203+
sections:
204+
- title: Recipes
205+
dir: recipes
206+
navbar_after: User Guide
57207
```
58208
59-
Opens the built site in your browser.
209+
See the [Configuration Guide](https://posit-dev.github.io/great-docs/user-guide/configuration.html) for the full reference.
60210
61-
### Deploy
211+
## Deploying to GitHub Pages
62212
63213
```bash
64214
great-docs setup-github-pages
65215
```
66216

67-
Creates a GitHub Actions workflow for automatic deployment.
217+
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.
218+
219+
## Recipes
68220

69-
## What You Get
221+
The documentation includes 18 step-by-step recipes:
70222

71-
- **Landing page** from your README with a metadata sidebar (authors, license, links)
72-
- **API reference** with classes, functions, and methods organized and styled
73-
- **CLI reference** with `--help` output in terminal style
74-
- **User Guide** from your `user_guide/` directory
75-
- **Source links** to GitHub for every documented item
76-
- **Mobile-friendly** responsive design
223+
| Recipe | Topic |
224+
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
225+
| [Hide Internal Symbols](https://posit-dev.github.io/great-docs/recipes/hide-internal-symbols.html) | Control what appears in your API reference |
226+
| [Customize API Organization](https://posit-dev.github.io/great-docs/recipes/customize-api-organization.html) | Structure reference sections your way |
227+
| [Document a CLI](https://posit-dev.github.io/great-docs/recipes/document-a-cli.html) | Auto-generate CLI reference from Click |
228+
| [Cross-Reference Items](https://posit-dev.github.io/great-docs/recipes/cross-reference-items.html) | Link between documented objects |
229+
| [Add Custom CSS](https://posit-dev.github.io/great-docs/recipes/add-custom-css.html) | Override styles with your own SCSS |
230+
| [Choose Gradient Theme](https://posit-dev.github.io/great-docs/recipes/choose-gradient-theme.html) | Pick and customize navbar gradients |
231+
| [Add Logo & Favicon](https://posit-dev.github.io/great-docs/recipes/add-logo-favicon.html) | Brand your site with custom icons |
232+
| [Customize Announcement Banner](https://posit-dev.github.io/great-docs/recipes/customize-announcement-banner.html) | Add dismissible site-wide notices |
233+
| [Write Effective Docstrings](https://posit-dev.github.io/great-docs/recipes/write-effective-docstrings.html) | Get the most out of auto-generated docs |
234+
| [Add Images & Diagrams](https://posit-dev.github.io/great-docs/recipes/add-images-diagrams.html) | Include visuals in your documentation |
235+
| [Create Changelog](https://posit-dev.github.io/great-docs/recipes/create-changelog.html) | Pull changelog from GitHub Releases |
236+
| [GitHub Pages & CI](https://posit-dev.github.io/great-docs/recipes/github-pages-ci.html) | Automate deployment with Actions |
237+
| [Add Custom Domain](https://posit-dev.github.io/great-docs/recipes/add-custom-domain.html) | Serve docs from your own domain |
238+
| [Install Great Docs Skill](https://posit-dev.github.io/great-docs/recipes/install-great-docs-skill.html) | Generate an Agent Skill for your package |
239+
| [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 |
240+
| [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 |
241+
| [Understand llms.txt](https://posit-dev.github.io/great-docs/recipes/understand-llms-txt.html) | Make your docs AI-accessible |
242+
| [Fix Common Build Errors](https://posit-dev.github.io/great-docs/recipes/fix-common-build-errors.html) | Troubleshoot build issues quickly |
77243

78244
## Documentation
79245

80-
The User Guide covers:
81-
82-
- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html)
83-
- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html)
84-
- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html)
85-
- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html)
86-
- [Cross-Referencing](https://posit-dev.github.io/great-docs/user-guide/cross-referencing.html)
87-
- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html)
88-
- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html)
89-
- [User Guides](https://posit-dev.github.io/great-docs/user-guide/user-guides.html)
90-
- [Custom Sections](https://posit-dev.github.io/great-docs/user-guide/custom-sections.html)
91-
- [Blog](https://posit-dev.github.io/great-docs/user-guide/blog.html)
92-
- [Building & Previewing](https://posit-dev.github.io/great-docs/user-guide/building.html)
93-
- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html)
94-
- [Link Checker](https://posit-dev.github.io/great-docs/user-guide/link-checker.html)
95-
- [Spell Checking](https://posit-dev.github.io/great-docs/user-guide/spell-checker.html)
96-
- [Changelog](https://posit-dev.github.io/great-docs/user-guide/changelog.html)
246+
Full documentation is available at **[posit-dev.github.io/great-docs](https://posit-dev.github.io/great-docs/)**:
247+
248+
- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html) — setup and requirements
249+
- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html) — first site in minutes
250+
- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html) — every option explained
251+
- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html) — gradients, colors, dark mode
252+
- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html) — how API references are generated
253+
- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html) — documenting Click CLIs
254+
- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html) — GitHub Pages and beyond
255+
256+
## Requirements
257+
258+
- **Python 3.11+**
259+
- **[Quarto](https://quarto.org/docs/get-started/)** (the rendering engine)
260+
261+
## Contributing
262+
263+
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).
97264

98265
## License
99266

100-
MIT License. See [LICENSE](https://posit-dev.github.io/great-docs/license.html) for details.
267+
MIT License. See [LICENSE](LICENSE) for details.
268+
269+
---
270+
271+
<p align="center">
272+
Built by <a href="https://posit.co">Posit</a>
273+
</p>

0 commit comments

Comments
 (0)