Internationalization
June 3, 2026 ยท View on GitHub
Documentation sites for Python packages: start simple, go deep
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.
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 initinspects 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
pip install great-docs
Initialize, build, and preview
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.
See more: class page and method page
CLI Reference
Click-based CLIs get rich, sectioned reference pages with usage signatures, typed options, and descriptions extracted directly from code. Each command page includes structured documentation alongside a collapsible --help output view.
MCP Server Reference
If your package ships an MCP server, Great Docs generates structured reference pages for every tool, resource, and prompt it exposes. Parameters, types, required/optional markers, and descriptions are extracted automatically from your server definitions.
Terminal Recordings
Teach your CLI visually with Termshow: record terminal sessions, edit them in a browser-based visual editor, and embed the results as animated SVG players in your documentation. Recordings are lightweight, theme-aware, and play inline without JavaScript dependencies. It so incredibly useful in onboarding guides, tutorials, and landing pages.
Dark Mode
A persistent dark mode toggle with flash-free loading. Your users' preference is remembered across visits.
Full Feature Set
|
Documentation Generation
|
Site Features
|
|
AI & LLM Integration
|
Configuration & Branding
|
|
Quality & Reliability
|
Deployment
|
|
Shortcodes & Widgets
|
Developer Experience
|
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:
# 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.
---
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 for the full reference.
Deploying to GitHub Pages
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 | Control what appears in your API reference |
| Customize API Organization | Structure reference sections your way |
| Document a CLI | Auto-generate CLI reference from Click |
| Cross-Reference Items | Link between documented objects |
| Write Effective Docstrings | Get the most out of auto-generated docs |
| Add Images & Diagrams | Include visuals in your documentation |
| Embed Videos | Add YouTube, Vimeo, and local videos |
Theming & Appearance
| Recipe | Topic |
|---|---|
| Add Custom CSS | Override styles with your own SCSS |
| Choose Gradient Theme | Pick and customize navbar gradients |
| Add Logo & Favicon | Brand your site with custom icons |
| Customize Announcement Banner | Add dismissible site-wide notices |
Publishing & Versioning
| Recipe | Topic |
|---|---|
| Create Changelog | Pull changelog from GitHub Releases |
| GitHub Pages & CI | Automate deployment with Actions |
| Add Custom Domain | Serve docs from your own domain |
| Enable Multi-Version Docs | Add a version selector to your site |
| Use Version Fences and Badges | Annotate version-specific content |
AI-Assisted Workflows
| Recipe | Topic |
|---|---|
| Install Great Docs Skill | Generate an Agent Skill for your package |
| Build Site with LLM | Use an AI assistant to set up your site |
| Customize Site with LLM | Use an AI assistant to tweak your site |
| Understand llms.txt | Make your docs AI-accessible |
Build & Quality
| Recipe | Topic |
|---|---|
| Fix Common Build Errors | Troubleshoot build issues quickly |
| Proofread Documentation | Catch spelling and grammar issues |
| Use Freeze Cache | Cache expensive notebooks across builds |
Documentation
Full documentation is available at posit-dev.github.io/great-docs:
- Installation: setup and requirements
- Quick Start: first site in minutes
- Configuration: every option explained
- API Documentation: how API references are generated
- CLI Documentation: documenting Click CLIs
- User Guides: adding prose documentation
- Custom Sections: recipes, blog, tutorials
- Custom Pages: static HTML pages
- Theming & Appearance: gradients, colors, dark mode
- Diagrams: Mermaid diagram pre-rendering
- Videos: embedding YouTube, Vimeo, and local videos
- Internationalization: 20+ language translations
- Deployment: GitHub Pages and beyond
- Multi-Version Docs: version selector and versioned builds
- API Evolution: tracking API changes across versions
- Freeze: caching expensive computations
- Scale to Fit: auto-shrink wide output
- Page Tags: categorize pages with tags
- Page Status Badges: lifecycle indicators
- Social Cards: Open Graph and Twitter cards
- Agent Skills: AI coding agent integration
- Link Checker: validate all links
- Proofreading: spelling & grammar checks
- Linting: documentation quality checks
- SEO: search engine optimization
- Terminal Recordings: record, edit, and embed terminal sessions
Requirements
- Python 3.11+
- Quarto (the rendering engine)
Contributing
Contributions are welcome! Please see CONTRIBUTING for guidelines and the Code of Conduct.
License
MIT License. See LICENSE for details.
Built by Posit, PBC.