ITADN
posit-dev/great-docs
代码 动态 Issues8 合并请求30 版本
posit-dev/great-docs · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Great Docs

Python 包的文档站点：从简单开始，深入细节

PyPI Python versions Downloads MIT License CI

Repo Status Great Docs Gauntlet

Documentation Contributors Ask DeepWiki Contributor Covenant

快速入门 · 功能 · 配置 · 配方 · 文档

[!TIP] 📺 在 Talk Python 上推荐： “Great Docs” 直播

观看 Great Docs 的实际演示，并了解其背后的故事：在 Talk Python 上的完整讲解。

Watch the Great Docs live stream on Talk Python

Great Docs 能在几分钟内将你的 Python 包转化为精美的文档站点。它会自动发现你的公共 API，检测你的 docstring 格式，生成结构化的参考页面，并渲染出现代化的站点，所有这一切只需一条命令。当你准备进行自定义时，有一套深入的工具和选项等着你。

并且它经过实战检验：每个版本都会在 Great Docs Gauntlet 中针对 300+ 合成包 运行，并由一套 15,600+ 的测试套件提供支持。

Great Docs in action: init, build, and preview a documentation site

三条命令，从零到上线站点。

Watch a 22-second tour of a generated Great Docs site

生成站点的 22 秒导览：浏览站点中许多有用的页面。Great Docs 自我文档化 -> 探索实时站点。

为什么选择 Great Docs？

编写文档不应比编写它所描述的代码更困难。大多数文档生成器要求你编写页面模板、手动组织内容并配置构建系统。Great Docs 颠覆了这一模式：只需指向一个 Python 包，即可立即获得一个出色的站点，然后按自己的节奏进一步探索。

  • 即时配置：great-docs init 检查你的包并生成完整的配置
  • 智能默认值：API 参考页面根据你的代码自动创建（无需手动编写）
  • 真实文档，而非存根：从你现有的 docstring 中渲染完整的参数表、返回类型、示例和交叉引用
  • 开箱即用的美观外观：渐变导航栏、深色模式、响应式布局、GitHub 小部件、侧边栏搜索、键盘导航
  • 需要时深入：用户指南、多版本文档、冻结缓存、链接检查、校对、SEO、国际化（20+ 种语言）等（均为可选）
  • AI 就绪：自动生成 llms.txt、智能体技能和供 LLM 使用的 markdown 页面
  • 随处部署：一条命令即可为 GitHub Pages 创建 GitHub Actions 工作流

对比

大多数 Python 文档工具给你一个框架，并要求你自己组装站点。Great Docs 首先为你组装一个完整的站点，然后在你需要控制时退居幕后。

Great DocsSphinxMkDocspdoc
零配置即可生成精美站点✅➖➖✅
从 docstring 生成 API 参考✅✅plugin✅
散文指南、食谱、自定义页面✅✅✅➖
Click CLI 以及 MCP 服务器参考✅➖➖➖
内置深色模式、搜索、主题定制✅themethemebasic
AI 就绪：llms.txt、智能体技能✅➖➖➖
链接检查、lint、校对、SEO✅partialplugins➖

Great Docs 基于 Quarto 构建，因此你可以获得其强大的渲染能力（可执行代码、数学公式、图表），而无需进行任何配置。

60 秒快速上手

[!IMPORTANT] Great Docs 需要你的系统具备两个条件：Python 3.11+ 和 Quarto（渲染引擎）。Quarto 是一个独立的、一次性安装的软件（它不是 Python 包），因此在运行以下命令之前请先安装它。详见 Requirements。

安装

pip install great-docs

初始化、构建和预览

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

就是这样。你的文档站点已准备就绪。

生成内容

由 Great Docs 构建的每个站点都包含：

落地页

你的 README 会被转换为一个包含英雄区域、元数据侧边栏（作者、许可证、链接）和快速入门说明的落地页。

API 参考

类、函数、方法和属性会自动组织到分类部分中。大型类会获得专属的方法页面。每个条目都链接回 GitHub 上的源代码。

API reference index with categorized sections

查看更多：类页面和方法页面

A class documentation page with parameters and methods

A method documentation page with signature and examples

CLI 参考

基于点击的 CLI 会获得丰富的、分节的参考页面，包含用法签名、类型化选项以及直接从代码中提取的描述。每个命令页面都包含结构化文档以及可折叠的 --help 输出视图。

CLI reference page with structured documentation and collapsible help output

MCP 服务器参考

如果你的软件包提供了一个 MCP 服务器，Great Docs 会为它暴露的每个工具、资源和提示生成结构化的参考页面。参数、类型、必填/可选标记和描述会自动从你的服务器定义中提取。标准 MCP 和 FastMCP 服务器都会被自动检测。

终端录制

使用 Termshow 以视觉方式教授你的 CLI：录制终端会话，在基于浏览器的可视化编辑器中编辑它们，并将结果作为动画 SVG 播放器嵌入到你的文档中。录制文件轻量级、支持主题感知，并且可以在没有 JavaScript 依赖的情况下内联播放。它在入门指南、教程和落地页中非常有用。

灯箱

任何图像都可以扩展为聚焦的全屏视图。为单个图像添加 .lightbox 类，或在页面上设置 lightbox: auto 以放大所有图像。查看器支持缩放和平移、带胶片条的多图像画廊、标题和署名、深色模式变体、图像注释、前后对比以及复制/下载工具栏。资源会自动加载，因此无需安装或启用任何内容。

深色模式

一个持久的深色模式切换开关，加载时无闪烁。用户的偏好会在多次访问中记住。

Documentation site in dark mode

完整功能集

80+ capabilities across 8 categories (click to expand)

文档生成

  • 通过 __all__、dir() 或静态分析自动发现导出项
  • 检测 NumPy、Google 和 Sphinx 文档字符串格式
  • 13 种对象类型，支持智能分类
  • Click CLI 文档
  • 来自 user_guide/ 目录的用户指南页面
  • 自定义章节（食谱、博客、教程等）
  • 支持直通或原始布局的自定义 HTML 页面
  • 带版本选择器的多版本文档
  • 视频嵌入（YouTube、Vimeo、本地文件）
  • Mermaid 图表预渲染（浅色 + 深色变体）
  • 支持冻结/缓存以处理高成本计算

站点特性

  • 深色模式切换，偏好设置持久化
  • 灯箱图片查看器（缩放、平移、画廊）
  • GitHub 组件，实时显示 star/fork 数量
  • 侧边栏搜索过滤器，适用于大型 API
  • 每个条目均提供指向 GitHub 的源链接
  • 代码块一键复制到剪贴板
  • 响应式、移动端友好的布局
  • 页面标签及标签索引页
  • 页面状态徽章（experimental、stable、deprecated）
  • API 演进注释（new、changed、deprecated）
  • 社交卡片（Open Graph / Twitter）
  • 键盘导航，附带快捷键覆盖层
  • 返回顶部浮动按钮
  • 导航图标（Lucide 图标集）
  • 宽 HTML 输出的自适应缩放

AI 与 LLM 集成

  • 自动生成 llms.txt 和 llms-full.txt
  • Agent Skills 生成（符合 agentskills.io 规范）
  • 每个包支持多个命名技能
  • 技能安装/检查/列表 CLI 命令
  • 为 LLM 消费生成 Markdown 页面
  • MCP 服务器参考页面（工具、资源、提示词）

配置与品牌

  • 公告横幅（可关闭，带样式）
  • 支持浅色/深色变体的 Logo
  • 自定义 favicon 和 Open Graph 图片
  • 支持 ORCID 的作者元数据
  • 来自 GitHub Releases 的更新日志
  • 国际化（20+ 种语言）
  • 强调色（全局或按模式）
  • 导航栏渐变预设或纯色
  • 内容区域渐变预设

质量与可靠性

  • 内置链接检查器
  • 文档检查器（docstrings、交叉引用、风格）
  • 校对（拼写与语法）
  • SEO 审计（sitemap、robots.txt、规范 URL、结构化数据）
  • 版本间的 API 差异
  • 构建耗时报告
  • 通过 Great Docs Gauntlet 对 300+ 个合成包进行测试
  • 15,600+ 个测试

部署

  • 一键 GitHub Pages 配置
  • GitHub Actions 工作流生成
  • 多版本部署及版本选择器
  • 浮动版本别名（/v/latest/, /v/stable/, /v/dev/）
  • 自定义域名支持
  • 静态输出：可托管于任意位置

Shortcodes & Widgets

  • 色板（内联和网格）
  • Lightbox（缩放、图库、注释、前后对比）
  • 终端录制（录制、编辑、嵌入）
  • 可折叠的详细信息部分
  • 键盘按键样式
  • 带强调色的水平分隔线
  • 表格预览（用于笔记本的 Python API）
  • 表格浏览器（交互式数据表格）

开发者体验

  • great-docs init 自动检测包管理器（uv, poetry, pip）
  • great-docs freeze 用于缓存昂贵计算
  • great-docs timings 用于构建性能洞察
  • 预渲染脚本钩子
  • 页面元数据时间戳（创建/修改日期）

配置

所有配置都位于项目根目录下的单个 great-docs.yml 文件中。init 命令会为您生成该文件，但您可以自定义所有内容：

# 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

自定义 HTML 页面可以放置在 custom/ 目录中，并在构建期间自动发现。

---
title: Landing Page
layout: passthrough
navbar: true
---
<section class="hero">...</section>

使用 layout: passthrough 将 HTML 主体包裹在标准的 Great Docs 外壳中，或使用 layout: raw 原样复制 HTML 文件。 设置 navbar: true 以使用其标题将页面添加到站点导航栏，或使用 navbar: {text: Showcase, after: Guide} 指定导航栏标签和位置。

请参阅 配置指南 获取完整参考。

部署到 GitHub Pages

great-docs setup-github-pages

这会创建一个 .github/workflows/ 文件，在每次推送到 main 时构建并发布你的站点。你的文档会自动与代码保持同步。

CLI 命令

除了 init、build 和 preview 之外，Great Docs 还包含一套完整的质量和维护工具：

命令用途
great-docs scan在构建前预览发现的导出项
great-docs lint检查缺失的 docstring、损坏的交叉引用和样式问题
great-docs proofread捕获拼写和语法问题
great-docs check-links验证已构建站点中的所有链接
great-docs seo审计 SEO 健康状况（sitemap、meta 标签、结构化数据）
great-docs api-diff OLD NEW显示两个版本之间的 API 变更
great-docs api-snapshot捕获公共 API 的 JSON 快照
great-docs versions列出并验证多版本配置
great-docs changelog从 GitHub Releases 生成变更日志
great-docs freeze执行特定页面并持久化其冻结缓存
great-docs timings显示上次构建的页面级构建耗时
great-docs setup-github-pages为 GitHub Pages 部署创建 CI 工作流
great-docs config生成完全文档化的配置模板
great-docs uninstall从你的项目中移除 great-docs
great-docs skill install为你的包安装 AI 代理技能
great-docs skill check检查已安装的技能是否为最新版本
great-docs skill list从包或 URL 列出可用技能
great-docs termshow record将终端会话记录为 .termshow 文件
great-docs termshow edit为录制打开基于浏览器的可视化编辑器
great-docs termshow play在终端中预览录制
great-docs termshow render无需完整站点构建即可渲染 SVG 帧
great-docs termshow import-cast导入 asciinema .cast 文件

配方

文档包含 24 个分步配方。

浏览全部 24 个配方（点击展开）

内容与 API

配方主题
隐藏内部符号控制 API 参考中显示的内容
自定义 API 组织方式按您的方式组织参考章节
记录 CLI从 Click 自动生成 CLI 参考
交叉引用条目在已记录的对象之间建立链接
编写有效的文档字符串充分利用自动生成的文档
添加图像和图表在文档中包含视觉元素
嵌入视频添加 YouTube、Vimeo 和本地视频

主题与外观

配方主题
添加自定义 CSS使用您自己的 SCSS 覆盖样式
选择渐变主题选择并自定义导航栏渐变
添加 Logo 和 Favicon使用自定义图标为您的网站添加品牌
自定义公告横幅添加可关闭的站点范围通知

发布与版本控制

配方主题
创建 Changelog从 GitHub Releases 拉取 Changelog
GitHub Pages & CI使用 Actions 自动化部署
添加自定义域名从您的自有域名提供文档
启用多版本文档为您的站点添加版本选择器
使用版本围栏和徽章标注特定版本的内容

AI 辅助工作流

配方主题
安装 Great Docs Skill为您的包生成一个 Agent Skill
使用 LLM 构建站点使用 AI 助手设置您的站点
使用 LLM 自定义站点使用 AI 助手调整您的站点
理解 llms.txt使您的文档可被 AI 访问

构建与质量

配方主题
修复常见构建错误快速排查构建问题
校对文档发现拼写和语法问题
使用冻结缓存在构建之间缓存昂贵的笔记本

文档

完整文档可在 posit-dev.github.io/great-docs 获取。

完整指南索引（27 页，点击展开）

要求

  • Python 3.11+
  • Quarto (the rendering engine)

贡献

欢迎贡献！请参阅 CONTRIBUTING 了解指南以及 Code of Conduct。

许可证

MIT License。详见 LICENSE。

由 Posit, PBC 构建。