使用 Docker 容器化构建 Plano 文档站点Sphinx 构建系统实战解析【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano导读Plano 的官方文档站点docs/采用 reStructuredTextRST书写源码、Sphinx 渲染 HTML并通过 Dockerfile 与 build_docs.sh 实现一键容器化构建。本文以 docs/README.md 的构建说明为主线深入拆解 Plano 文档的目录结构、Docker 构建镜像、Sphinx 主题配置、本地扩展与自定义 JS 的完整实现帮助你快速复现文档构建流程并理解其面向搜索引擎与 LLM 的工程化设计。一、总览Plano 文档构建的核心流程Plano 的文档站点不是手写 HTML而是一套完整的 Sphinx 文档工程写作语言reStructuredText.rst全部源码位于 docs/source构建工具Sphinx sphinxawesome_theme主题构建方式以 Dockerfile 制作统一镜像再由 build_docs.sh 挂载源码卷执行make html产物docs/build/html下的静态站点发布域名由 docs/CNAMEdocs.planoai.dev指定。启动构建仅需两条信息执行sh build_docs.sh且本机需安装并运行 Docker。整个流程如下图所示sh build_docs.sh │ ▼ docker build -f docs/Dockerfile . -t sphinx # 1. 构建镜像安装 Sphinx 依赖 │ ▼ rm -rf docs/build mkdir -p docs/build # 2. 清理并准备输出目录 │ ▼ docker run ... sphinx make clean # 3. 在容器内清理旧产物 │ ▼ docker run ... sphinx make html # 4. 在容器内生成 HTML 站点 │ ▼ docs/build/html/ # 5. 静态站点产物二、构建入口build_docs.sh 逐行拆解build_docs.sh 是构建的唯一入口全文仅 22 行却完整覆盖了镜像构建 → 目录清理 → 容器内构建 → 权限修复四个阶段set -e docker build -f docs/Dockerfile . -t sphinx # Clean build output locally rm -rf docs/build mkdir -p docs/build chmod -R 777 docs/build # Run make clean/html while keeping provider_models.yaml from the image docker run --user $(id -u):$(id -g) --rm \ -v $(pwd)/docs/source:/docs/source \ -v $(pwd)/docs/Makefile:/docs/Makefile \ -v $(pwd)/docs/build:/docs/build \ sphinx make clean docker run --user $(id -u):$(id -g) --rm \ -v $(pwd)/docs/source:/docs/source \ -v $(pwd)/docs/Makefile:/docs/Makefile \ -v $(pwd)/docs/build:/docs/build \ sphinx make html chmod -R 777 docs/build/html关键设计点set -e任一命令失败立即终止保证构建失败不会被静默吞掉镜像名sphinx基于 sphinxdoc/sphinx 官方镜像扩展由 docs/Dockerfile 定义卷挂载-v只把docs/sourceRST 源码、docs/Makefile构建目标和docs/build产物目录挂进容器镜像本身保持只读、可复用--user $(id -u):$(id -g)以宿主机当前用户身份运行避免容器内 root 生成的产物归属混乱--rm容器执行完自动删除不残留中间容器两次make先make clean清空旧产物再make html生成最新站点确保输出目录幂等权限兜底末尾chmod -R 777 docs/build/html规避不同环境下的文件权限问题。MakefileSphinx 的标准代理Makefile 是 Sphinx 工程的标准最小实现SOURCEDIR source、BUILDDIR build所有未知目标如html、clean统一路由到sphinx-build -M 目标 source build。容器内执行的sphinx make html实际上等价于sphinx-build -M html source build产物落在build/html。三、构建镜像Dockerfile 与依赖清单Dockerfile 以sphinxdoc/sphinx为基础镜像在/docs工作目录中安装 Plano 文档所需的全部 Python 依赖FROM sphinxdoc/sphinx WORKDIR /docs COPY docs/requirements.txt /docs RUN python3 -m pip install -r requirements.txt RUN pip freeze # Copy provider_models.yaml from the repo for documentation COPY crates/hermesllm/src/bin/provider_models.yaml /docs/provider_models.yaml三个值得注意的细节RUN pip freeze构建时输出完整依赖版本清单便于排查依赖漂移provider_models.yaml 随镜像打入将crates/hermesllm/src/bin/provider_models.yamlLLM 提供方模型清单复制进镜像的/docs/provider_models.yaml供文档构建期的provider_models扩展读取源码经卷挂载而非 COPYRST 源文件在运行时通过-v挂载因此改文档无需重新构建镜像迭代速度更快。依赖清单 requirements.txt 共 4 项依赖版本约束作用sphinx_copybutton0.5.2为代码块提供一键复制按钮sphinxawesome-theme6.0.0站点主题含面包屑、导航、图标sphinx_sitemap最新生成 sitemap.xml利于搜索引擎收录sphinx_design最新提供 tab-set、卡片等 UI 组件四、Sphinx 核心配置conf.py 深度解读conf.py 是文档站点的中枢配置聚合了项目信息、扩展加载、主题定制与自定义角色注册。4.1 项目元信息project Plano Docs copyright 2026, Katanemo Labs, a DigitalOcean Company author Katanemo Labs, Inc release v0.4.35release v0.4.35表明当前文档对应的 Plano 版本html_title project release会将其拼入页面标题。注意root_doc index指定首页入口为 docs/source/index.rstnitpicky True开启严格告警——所有交叉引用必须有效防止文档出现死链。4.2 扩展体系extensions [ sphinx.ext.autodoc, sphinx.ext.intersphinx, sphinx.ext.extlinks, sphinx.ext.mathjax, sphinx.ext.viewcode, sphinx_sitemap, sphinx_design, # Local extensions llms_txt, provider_models, ]除 Sphinx 官方扩展外Plano 自带两个本地扩展源码位于 docs/source/_ext通过sys.path.insert(0, ...)注入_ext目录后按模块名加载llms_txtllms_txt.py在 HTML 构建完成后自动生成includes/llms.txt。它遍历 Sphinx 环境中的所有文档排除genindex、search提取标题与纯文本组装成一份带目录和生成时间的llms.txt。这份机器可读文本正是为了让 Agent 与 LLM 快速理解文档结构而设计的provider_modelsprovider_models.py构建结束后把镜像内的provider_models.yaml复制到输出目录的includes/provider_models.yaml使构建产物自包含模型清单数据。两个扩展都实现了parallel_read_safe True/parallel_write_safe True声明可安全并行读写不影响 Sphinx 的多进程构建。4.3 主题与页面结构站点使用sphinxawesome_theme并做了多项裁剪html_use_index False # 不生成索引页 html_domain_indices False # 不需要模块索引 html_copy_source False # 不复制 RST 源码到站点 html_show_sphinx False # 隐藏 Sphinx 品牌脚注 html_sidebars { **: [ analytics.html, sidebar_main_nav_links.html, sidebar_toc.html, ] }侧边栏自定义了三块Google Analytics 统计模板、主导航链接与目录树。html_theme_options通过ThemeOptionsdataclass 配置开启面包屑show_breadcrumbsTrue与外部链接图标awesome_external_linksTrue并在页头注入 GitHub 仓库图标链接。4.4 代码高亮与统计pygments_style lovelace pygments_style_dark github-dark sitemap_url_scheme {link} html_context { google_analytics_id: G-EH2VW19FXE, }明暗双主题代码高亮浅色用lovelace深色用github-darksitemap_url_scheme {link}配合sphinx_sitemap扩展生成 sitemap助力搜索引擎抓取html_context注入 GA 统计 ID由 analytics.html 模板渲染 gtag 脚本含{% if google_analytics_id %}条件判断未配置时不输出。4.5 自定义 confval 角色conf.py末尾的setup()通过app.add_object_type注册了confval角色与指令支持:confval:交叉引用以及带default字段的参数文档便于在 RST 中规范化描述配置项app.add_object_type( confval, confval, objnameconfiguration parameter, doc_field_types[Field(default, labeldefault, has_argTrue, ...)], )五、自定义资源样式、脚本与模板5.1 复制按钮缺陷修复fix-copy.jsfix-copy.js 是一个典型的构建产物质量修补案例sphinxawesome_theme会在每个pre内插入复制按钮但 clipboard 复制时会把按钮的 sr-only 文本Copy code一并复制进剪贴板。该脚本在copy事件捕获阶段拦截用正则/\nCopy code\s*$/剥离尾部残留后重写剪贴板数据。这保证了用户复制代码块时得到干净内容。5.2 统计模板analytics.htmlanalytics.html 是 Jinja2 模板仅在google_analytics_id存在时输出 gtag 脚本实现了配置驱动的统计注入。5.3 样式入口globals.css 之外的自定义样式 通过html_css_files [css/custom.css]挂载覆盖主题默认样式配合 PlanoTagline.svg 等静态资源构成完整品牌视觉。六、文档目录结构source 之下的内容组织Sphinx 站点内容全部位于 docs/source按主题划分为四个一级目录由 index.rst 通过tab-set与多个toctree组织导航目录内容代表文档get_started/入门指南overview、intro_to_plano、quickstartconcepts/核心概念listeners、agents、filter_chain、llm_providers/llm_providers、prompt_target、signalsguides/实操指南orchestration、llm_router、function_calling、observability/observability、prompt_guard、stateresources/参考资源tech_overview/tech_overview、deployment、configuration_reference、cli_reference、llms_txt这种入门 / 概念 / 指南 / 资源的 Diátaxis 式分层使不同阶段的读者新手、集成者、运维者都能快速定位。concepts/llm_providers/等二级目录对应 RST 文件中的llm_providers/llm_providers引用方式。七、构建产物与 LLM 友好设计构建完成后docs/build/html目录包含index.html及全部 RST 渲染出的 HTML 页面sitemap.xml由sphinx_sitemap生成includes/llms.txt由llms_txt扩展自动生成includes/provider_models.yaml由provider_models扩展从镜像内复制。其中llms.txt是 Plano 文档面向 AI 时代的独特设计它以纯文本列出全部文档标题与文件路径并逐篇输出提炼后的正文让搜索引擎、Agent 与 LLM 无需抓取整站即可理解文档全貌。生成逻辑在 llms_txt.py 的_render_llms_txt()中头部的生成时间戳UTC与版本号确保了机器读取时的时效性判断。八、常见问题与排查建议现象排查方向docker build失败确认 Docker 已安装并启动docs/README.md 中的唯一前置条件检查网络能否拉取sphinxdoc/sphinx基础镜像构建报错但信息不足脚本带set -e任一步失败即中止可手动重跑docker run ... sphinx make html查看完整 Sphinx 日志产物文件权限异常检查是否以--user $(id -u):$(id -g)运行构建末尾的chmod -R 777可作兜底新增 RST 页面未出现在导航需在 index.rst 对应toctree中登记或在页面内通过toctree引用交叉引用失效nitpicky True会在构建时直接告警按日志补全:ref:/:doc:目标即可llms.txt 未生成确认llms_txt扩展已加载conf.py 的extensions列表且构建目标为 HTML九、总结Plano 的文档构建体系体现了工程化文档的思路Docker 镜像锁定了构建环境卷挂载让文档迭代无需重建镜像llms.txt与 sitemap 扩展兼顾了人类阅读与机器检索fix-copy.js则打磨了代码复制的使用体验。对于希望复现或借鉴该流程的开发者核心入口是 build_docs.sh 与 Dockerfile配置中枢是 conf.py而内容组织则参照 index.rst 的目录结构即可快速上手。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Docker 容器化构建 Plano 文档站点：Sphinx 构建系统实战解析
使用 Docker 容器化构建 Plano 文档站点Sphinx 构建系统实战解析【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano导读Plano 的官方文档站点docs/采用 reStructuredTextRST书写源码、Sphinx 渲染 HTML并通过 Dockerfile 与 build_docs.sh 实现一键容器化构建。本文以 docs/README.md 的构建说明为主线深入拆解 Plano 文档的目录结构、Docker 构建镜像、Sphinx 主题配置、本地扩展与自定义 JS 的完整实现帮助你快速复现文档构建流程并理解其面向搜索引擎与 LLM 的工程化设计。一、总览Plano 文档构建的核心流程Plano 的文档站点不是手写 HTML而是一套完整的 Sphinx 文档工程写作语言reStructuredText.rst全部源码位于 docs/source构建工具Sphinx sphinxawesome_theme主题构建方式以 Dockerfile 制作统一镜像再由 build_docs.sh 挂载源码卷执行make html产物docs/build/html下的静态站点发布域名由 docs/CNAMEdocs.planoai.dev指定。启动构建仅需两条信息执行sh build_docs.sh且本机需安装并运行 Docker。整个流程如下图所示sh build_docs.sh │ ▼ docker build -f docs/Dockerfile . -t sphinx # 1. 构建镜像安装 Sphinx 依赖 │ ▼ rm -rf docs/build mkdir -p docs/build # 2. 清理并准备输出目录 │ ▼ docker run ... sphinx make clean # 3. 在容器内清理旧产物 │ ▼ docker run ... sphinx make html # 4. 在容器内生成 HTML 站点 │ ▼ docs/build/html/ # 5. 静态站点产物二、构建入口build_docs.sh 逐行拆解build_docs.sh 是构建的唯一入口全文仅 22 行却完整覆盖了镜像构建 → 目录清理 → 容器内构建 → 权限修复四个阶段set -e docker build -f docs/Dockerfile . -t sphinx # Clean build output locally rm -rf docs/build mkdir -p docs/build chmod -R 777 docs/build # Run make clean/html while keeping provider_models.yaml from the image docker run --user $(id -u):$(id -g) --rm \ -v $(pwd)/docs/source:/docs/source \ -v $(pwd)/docs/Makefile:/docs/Makefile \ -v $(pwd)/docs/build:/docs/build \ sphinx make clean docker run --user $(id -u):$(id -g) --rm \ -v $(pwd)/docs/source:/docs/source \ -v $(pwd)/docs/Makefile:/docs/Makefile \ -v $(pwd)/docs/build:/docs/build \ sphinx make html chmod -R 777 docs/build/html关键设计点set -e任一命令失败立即终止保证构建失败不会被静默吞掉镜像名sphinx基于 sphinxdoc/sphinx 官方镜像扩展由 docs/Dockerfile 定义卷挂载-v只把docs/sourceRST 源码、docs/Makefile构建目标和docs/build产物目录挂进容器镜像本身保持只读、可复用--user $(id -u):$(id -g)以宿主机当前用户身份运行避免容器内 root 生成的产物归属混乱--rm容器执行完自动删除不残留中间容器两次make先make clean清空旧产物再make html生成最新站点确保输出目录幂等权限兜底末尾chmod -R 777 docs/build/html规避不同环境下的文件权限问题。MakefileSphinx 的标准代理Makefile 是 Sphinx 工程的标准最小实现SOURCEDIR source、BUILDDIR build所有未知目标如html、clean统一路由到sphinx-build -M 目标 source build。容器内执行的sphinx make html实际上等价于sphinx-build -M html source build产物落在build/html。三、构建镜像Dockerfile 与依赖清单Dockerfile 以sphinxdoc/sphinx为基础镜像在/docs工作目录中安装 Plano 文档所需的全部 Python 依赖FROM sphinxdoc/sphinx WORKDIR /docs COPY docs/requirements.txt /docs RUN python3 -m pip install -r requirements.txt RUN pip freeze # Copy provider_models.yaml from the repo for documentation COPY crates/hermesllm/src/bin/provider_models.yaml /docs/provider_models.yaml三个值得注意的细节RUN pip freeze构建时输出完整依赖版本清单便于排查依赖漂移provider_models.yaml 随镜像打入将crates/hermesllm/src/bin/provider_models.yamlLLM 提供方模型清单复制进镜像的/docs/provider_models.yaml供文档构建期的provider_models扩展读取源码经卷挂载而非 COPYRST 源文件在运行时通过-v挂载因此改文档无需重新构建镜像迭代速度更快。依赖清单 requirements.txt 共 4 项依赖版本约束作用sphinx_copybutton0.5.2为代码块提供一键复制按钮sphinxawesome-theme6.0.0站点主题含面包屑、导航、图标sphinx_sitemap最新生成 sitemap.xml利于搜索引擎收录sphinx_design最新提供 tab-set、卡片等 UI 组件四、Sphinx 核心配置conf.py 深度解读conf.py 是文档站点的中枢配置聚合了项目信息、扩展加载、主题定制与自定义角色注册。4.1 项目元信息project Plano Docs copyright 2026, Katanemo Labs, a DigitalOcean Company author Katanemo Labs, Inc release v0.4.35release v0.4.35表明当前文档对应的 Plano 版本html_title project release会将其拼入页面标题。注意root_doc index指定首页入口为 docs/source/index.rstnitpicky True开启严格告警——所有交叉引用必须有效防止文档出现死链。4.2 扩展体系extensions [ sphinx.ext.autodoc, sphinx.ext.intersphinx, sphinx.ext.extlinks, sphinx.ext.mathjax, sphinx.ext.viewcode, sphinx_sitemap, sphinx_design, # Local extensions llms_txt, provider_models, ]除 Sphinx 官方扩展外Plano 自带两个本地扩展源码位于 docs/source/_ext通过sys.path.insert(0, ...)注入_ext目录后按模块名加载llms_txtllms_txt.py在 HTML 构建完成后自动生成includes/llms.txt。它遍历 Sphinx 环境中的所有文档排除genindex、search提取标题与纯文本组装成一份带目录和生成时间的llms.txt。这份机器可读文本正是为了让 Agent 与 LLM 快速理解文档结构而设计的provider_modelsprovider_models.py构建结束后把镜像内的provider_models.yaml复制到输出目录的includes/provider_models.yaml使构建产物自包含模型清单数据。两个扩展都实现了parallel_read_safe True/parallel_write_safe True声明可安全并行读写不影响 Sphinx 的多进程构建。4.3 主题与页面结构站点使用sphinxawesome_theme并做了多项裁剪html_use_index False # 不生成索引页 html_domain_indices False # 不需要模块索引 html_copy_source False # 不复制 RST 源码到站点 html_show_sphinx False # 隐藏 Sphinx 品牌脚注 html_sidebars { **: [ analytics.html, sidebar_main_nav_links.html, sidebar_toc.html, ] }侧边栏自定义了三块Google Analytics 统计模板、主导航链接与目录树。html_theme_options通过ThemeOptionsdataclass 配置开启面包屑show_breadcrumbsTrue与外部链接图标awesome_external_linksTrue并在页头注入 GitHub 仓库图标链接。4.4 代码高亮与统计pygments_style lovelace pygments_style_dark github-dark sitemap_url_scheme {link} html_context { google_analytics_id: G-EH2VW19FXE, }明暗双主题代码高亮浅色用lovelace深色用github-darksitemap_url_scheme {link}配合sphinx_sitemap扩展生成 sitemap助力搜索引擎抓取html_context注入 GA 统计 ID由 analytics.html 模板渲染 gtag 脚本含{% if google_analytics_id %}条件判断未配置时不输出。4.5 自定义 confval 角色conf.py末尾的setup()通过app.add_object_type注册了confval角色与指令支持:confval:交叉引用以及带default字段的参数文档便于在 RST 中规范化描述配置项app.add_object_type( confval, confval, objnameconfiguration parameter, doc_field_types[Field(default, labeldefault, has_argTrue, ...)], )五、自定义资源样式、脚本与模板5.1 复制按钮缺陷修复fix-copy.jsfix-copy.js 是一个典型的构建产物质量修补案例sphinxawesome_theme会在每个pre内插入复制按钮但 clipboard 复制时会把按钮的 sr-only 文本Copy code一并复制进剪贴板。该脚本在copy事件捕获阶段拦截用正则/\nCopy code\s*$/剥离尾部残留后重写剪贴板数据。这保证了用户复制代码块时得到干净内容。5.2 统计模板analytics.htmlanalytics.html 是 Jinja2 模板仅在google_analytics_id存在时输出 gtag 脚本实现了配置驱动的统计注入。5.3 样式入口globals.css 之外的自定义样式 通过html_css_files [css/custom.css]挂载覆盖主题默认样式配合 PlanoTagline.svg 等静态资源构成完整品牌视觉。六、文档目录结构source 之下的内容组织Sphinx 站点内容全部位于 docs/source按主题划分为四个一级目录由 index.rst 通过tab-set与多个toctree组织导航目录内容代表文档get_started/入门指南overview、intro_to_plano、quickstartconcepts/核心概念listeners、agents、filter_chain、llm_providers/llm_providers、prompt_target、signalsguides/实操指南orchestration、llm_router、function_calling、observability/observability、prompt_guard、stateresources/参考资源tech_overview/tech_overview、deployment、configuration_reference、cli_reference、llms_txt这种入门 / 概念 / 指南 / 资源的 Diátaxis 式分层使不同阶段的读者新手、集成者、运维者都能快速定位。concepts/llm_providers/等二级目录对应 RST 文件中的llm_providers/llm_providers引用方式。七、构建产物与 LLM 友好设计构建完成后docs/build/html目录包含index.html及全部 RST 渲染出的 HTML 页面sitemap.xml由sphinx_sitemap生成includes/llms.txt由llms_txt扩展自动生成includes/provider_models.yaml由provider_models扩展从镜像内复制。其中llms.txt是 Plano 文档面向 AI 时代的独特设计它以纯文本列出全部文档标题与文件路径并逐篇输出提炼后的正文让搜索引擎、Agent 与 LLM 无需抓取整站即可理解文档全貌。生成逻辑在 llms_txt.py 的_render_llms_txt()中头部的生成时间戳UTC与版本号确保了机器读取时的时效性判断。八、常见问题与排查建议现象排查方向docker build失败确认 Docker 已安装并启动docs/README.md 中的唯一前置条件检查网络能否拉取sphinxdoc/sphinx基础镜像构建报错但信息不足脚本带set -e任一步失败即中止可手动重跑docker run ... sphinx make html查看完整 Sphinx 日志产物文件权限异常检查是否以--user $(id -u):$(id -g)运行构建末尾的chmod -R 777可作兜底新增 RST 页面未出现在导航需在 index.rst 对应toctree中登记或在页面内通过toctree引用交叉引用失效nitpicky True会在构建时直接告警按日志补全:ref:/:doc:目标即可llms.txt 未生成确认llms_txt扩展已加载conf.py 的extensions列表且构建目标为 HTML九、总结Plano 的文档构建体系体现了工程化文档的思路Docker 镜像锁定了构建环境卷挂载让文档迭代无需重建镜像llms.txt与 sitemap 扩展兼顾了人类阅读与机器检索fix-copy.js则打磨了代码复制的使用体验。对于希望复现或借鉴该流程的开发者核心入口是 build_docs.sh 与 Dockerfile配置中枢是 conf.py而内容组织则参照 index.rst 的目录结构即可快速上手。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考