TileLang 文档站构建指南Sphinx 依赖安装、本地构建预览与 CI 自动发布全解析【免费下载链接】tilelangDomain-specific language designed to streamline the development of high-performance GPU/CPU/Accelerators kernels项目地址: https://gitcode.com/GitHub_Trending/ti/tilelang本文以 TileLang 仓库的文档构建说明 docs/README.md 为核心完整讲清 TileLang 官方文档站从依赖安装、make html构建、本地 HTTP 预览到 CI 自动发布的完整工作流并结合 docs/conf.py、docs/Makefile 与 maint/scripts/build_docs.sh 等仓库内真实配置深入剖析构建背后的 Sphinx 主题、扩展与 autoapi 机制。读完后你可以独立完成文档站的本地构建与预览并理解线上文档部署于tilelang.com域名是如何由仓库内容自动生成的。一、文档目录结构与各文件职责TileLang 的文档源码全部位于仓库根目录下的docs/目录。理解各文件的分工是掌握构建流程的前提文件/目录职责docs/README.md文档构建的操作说明安装依赖、构建、预览三步docs/conf.pySphinx 全局配置主题、扩展、autoapi、输出选项docs/requirements.txt构建文档站所需的 Python 依赖清单docs/MakefileUnix/macOS 下驱动 Sphinx 的 Makefilemake html等目标docs/make.batWindows 下等价的批处理入口docs/index.md文档首页定义整个文档站的分栏目录树toctreedocs/CNAME声明文档站的正式域名tilelang.comdocs/_static/静态资源目录图片、custom.css自定义样式maint/scripts/build_docs.shCI 使用的构建脚本建 venv、装依赖、make html、拷贝 CNAME.github/workflows/publish-docs.ymlCI 发布工作流定义docs/README.md 开篇即说明文档构建在 Sphinx 之上。实际构建产物输出到docs/_build/html/这也是Makefile中BUILDDIR _build的含义。二、安装文档构建依赖按 docs/README.md 的官方步骤第一步是在docs/目录下执行pip3 install -r requirements.txt对应的依赖清单 docs/requirements.txt 内容如下逐行列出便于核对版本约束fastapi pydantic sphinx sphinx-reredirects sphinx-tabs sphinx-toolbox sphinxcontrib-napoleon sphinxcontrib_httpdomain furo uvicorn myst-parser sphinx-autoapi 3.6.0 astroid 4其中几个关键依赖值得结合 docs/conf.py 理解其作用sphinx-autoapi 3.6.0严格锁版本用于从tilelang源码包自动生成 API 参考文档。conf.py中配置autoapi_type python、autoapi_dirs [../tilelang]即自动扫描仓库根目录下的 tilelang 包并生成autoapi/tilelang/...文档树。锁定3.6.0是为了保证 API 文档生成行为在不同环境下可复现。astroid 4autoapi 3.x 依赖 astroid 做静态解析这里显式限制 4以保证兼容。furo文档站的主题conf.py中html_theme furo。myst-parser支持以 MarkdownMyST编写文档index.md中大量使用的:::{toctree}语法即由它解析。sphinx-reredirects处理旧页面 URL 跳转见下文重定向配置。sphinx-tabs/sphinx-toolbox/sphinxcontrib_httpdomain分别提供标签页、折叠块等 UI 组件与 HTTP 领域语法支持。fastapiuvicorn属于依赖清单中较特殊的成员从依赖组合看应为构建/调试文档服务流程的辅助组件文档主体渲染本身只依赖 Sphinx 生态。需要注意CI 构建脚本 maint/scripts/build_docs.sh 中安装依赖的等价写法是python -m pip install -r docs/requirements.txt --no-user在独立 venv 中执行本地手动构建时建议同样使用独立虚拟环境避免污染主环境。三、构建文档站make html背后的机制docs/README.md 给出的构建命令是make html其背后由 docs/Makefile 驱动。该 Makefile 是 Sphinx 官方推荐的“最小化 Makefile”核心变量与目标如下SPHINXOPTS ? SPHINXBUILD ? python -m sphinx SOURCEDIR . BUILDDIR _buildSPHINXBUILD固定使用python -m sphinx因此必须确保当前激活的 Python 环境已安装上述依赖SOURCEDIR .表示以docs/目录自身为文档源目录所以命令需在docs/内执行BUILDDIR _build与CNAME拷贝逻辑见第五节相呼应。Makefile 还有两个实用目标值得了解# 不带参数直接运行 make等价于 make help列出所有可用构建目标 help: $(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) $(O) # clean 目标会额外删除 autoapi 的生成目录确保完全干净的构建 clean: rm -rf $(BUILDDIR) autoapi当 autoapi 生成结果异常例如新增/删除了模块后 API 页面未更新时执行make clean make html可获得全新构建其余任意目标如html、latexpdf由 catch-all 规则%: Makefile透传给sphinx-build -M处理通过环境变量追加选项的用法SPHINXOPTS例如make html SPHINXOPTS-b html --jobs auto。在 Windows 平台上则使用等价的 docs/make.bat它先检查sphinx-build是否可用不可用时会提示安装 Sphinx随后以sphinx-build -M %1 . _build的方式路由构建目标。四、conf.py 深度解析主题、扩展与 API 文档生成docs/conf.py 是整个文档站行为的“总开关”主要配置可归纳为四组。4.1 项目元信息project TileLang br author Tile Lang Contributors copyright f2025-2025, {author} # Version information. with open(../VERSION) as f: version f.read().strip() release version版本号直接读取仓库根目录的VERSION文件保证文档站展示的版本与代码包版本一致。4.2 Sphinx 扩展与 API 文档生成extensions [ sphinx_tabs.tabs, sphinx_toolbox.collapse, sphinxcontrib.httpdomain, sphinx.ext.napoleon, sphinx.ext.intersphinx, sphinx_reredirects, sphinx.ext.mathjax, myst_parser, autoapi.extension, ] autoapi_type python autoapi_dirs [../tilelang] autoapi_options [ members, undoc-members, show-inheritance, show-module-summary, special-members, ] autoapi_keep_files False # Useful for debugging the generated rst files autoapi_generate_api_docs True autodoc_typehints description autoapi_ignore [*language/ast*, *version*, *libinfo*, *parser*]从这份配置可以确认几件实现事实API 参考部分index.md目录树中的autoapi/tilelang/index完全由autoapi 自动扫描tilelang/包生成而非手写生成时包含未文档化的成员undoc-members并展示继承关系show-inheritance且类型提示以autodoc_typehints description方式呈现*language/ast*、*version*、*libinfo*、*parser*等内部模块被autoapi_ignore排除在公开 API 之外调试技巧将autoapi_keep_files临时改为True可以保留 autoapi 生成的中间 rst 文件源码注释中明确标注了这一用途。4.3 源文件、Markdown 语法与排除规则source_suffix {.rst: restructuredtext, .md: markdown} myst_enable_extensions [colon_fence, deflist] redirects {get_started/try_out: ../index.html#getting-started} exclude_patterns [_build, Thumbs.db, .DS_Store, README.md, **/*libinfo*, **/*version*]文档主体以 Markdown 为主全部为.md同时兼容.rstcolon_fence扩展使:::{toctree}这类双冒号围栏可用这正是 docs/index.md 组织目录树的语法README.md本身被排除在构建外因此它只是给贡献者看的构建说明不会出现在线上文档站sphinx_reredirects的redirects配置保证历史 URL如get_started/try_out访问时跳转到index.html#getting-started避免旧链接失效。4.4 HTML 输出选项html_theme furo templates_path [] html_static_path [_static] html_css_files [custom.css] footer_copyright © 2025-2026 TileLang html_theme_options {light_logo: img/logo-v2.png, dark_logo: img/logo-v2.png}采用furo主题依赖清单中的furo包亮/暗两种模式均使用_static/img/logo-v2.png作为 Logodocs/_static/custom.css 为在主题之上叠加的自定义样式exclude_patterns中的_build防止构建产物递归进入源目录。五、文档内容体系index.md 的目录树构建出的文档站结构由 docs/index.md 中的多个toctree块决定当前线上文档分为以下板块路径均相对于docs/目录板块包含页面GET STARTEDInstallation、overview、targetsTUTORIALSdebug_tools_for_tilelang、auto_tuning、loggingTOOLStools/index、compile_only、analyzer、layout_visualization、autodd、lower_trace、pass_diff、iketPROGRAMMING GUIDESoverview、language_basics、instructions、control_flow、software_pipeline、python_compatibility、autotuning、type_systemDEEP LEARNING OPERATORSelementwise、gemv、matmul、matmul_sparse、deepseek_mlaCOMPILER INTERNALSletstmt_inline、inject_fence_proxy、tensor_checks、metal_tilelang_developmentDEVELOPER GUIDEcpp_styleAPI Referenceautoapi/tilelang/indexautoapi 自动生成Privacyprivacy新增文档页面时正确做法是在docs/对应子目录新增.md文件并在index.md相应toctree块中登记路径否则页面不会出现在导航中。六、本地预览启动 HTTP 服务器构建完成后按 docs/README.md 说明启动一个简单 HTTP 服务器cd _build/html python3 -m http.server然后访问http://localhost:8000查看文档。原文档特别指出端口可通过给命令追加-p PORT_NUMBER自定义例如python3 -m http.server -p 8080这一方式只适合本地查看由于构建产物是纯静态 HTMLSphinxhtmlbuilder 输出也可以直接双击index.html或在任意静态服务器中托管CNAME 文件则用于声明正式发布域名。七、CI 自动构建与发布流程本地三步装依赖 → 构建 → 预览之上仓库还配套了一条完整的 CI 发布链路适合想理解“文档站如何保持与 main 分支同步”的读者。7.1 构建脚本 build_docs.shmaint/scripts/build_docs.sh 是 CI 的执行入口完整逻辑为#!/usr/bin/env bash python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip --no-user python -m pip install -r docs/requirements.txt --no-user cd docs make html cp CNAME _build/html/它与手动流程的差异点有两处一是使用全新 venv 隔离环境二是构建完成后把 docs/CNAME 复制到_build/html/——该文件内容为tilelang.com托管平台据此把域名绑定到文档站根路径。7.2 发布工作流 publish-docs.yml.github/workflows/publish-docs.yml 定义了发布时机与步骤触发条件if表达式仅限tile-ai组织下的仓库且满足二者之一——pull_request_target事件PR 状态为 closed 且merged true、目标分支为main手动触发workflow_dispatch。 即只有合入 main 分支的 PR 才会自动重新发布文档运行环境runs-on: [self-hosted, nvidia]自建 runnerPython 版本固定3.10构建步骤bash -ex maint/scripts/build_docs.sh-ex便于失败定位发布步骤将构建产物推送到一个独立的目标仓库由TARGET_REPO/TARGET_TOKEN两个 secrets 指定先 clone 目标仓库main分支清空除.github外的旧内容再复制docs/_build/html/*用git status --porcelain判断是否有实际变更无变更则跳过提交。从源码结构看这种“构建仓库 → 独立发布仓库”的双仓库模式意味着文档站的静态站点内容与 TileLang 代码仓库解耦发布失败不会回滚代码且可以独立控制站点的静态托管。八、实操要点与常见注意事项结合上述配置本地构建文档站时建议注意以下事项必须在docs/目录内执行make htmlMakefile 的SOURCEDIR .依赖当前工作目录而conf.py中autoapi_dirs [../tilelang]等相对路径也是以docs/为基准解析的autoapi 锁定了sphinx-autoapi 3.6.0与astroid 4升级 Sphinx 或相关生态包时可能触发兼容问题遇到生成异常可先回到该版本组合增量构建异常时用make cleanclean会同时删除_build与autoapi生成目录再重新make html可解决 API 页面残留或目录树不同步的问题README.md不会出现在文档站中exclude_patterns显式排除了它它是构建指南而非文档页旧链接维护迁移或重命名页面后应在conf.py的redirects中登记映射现有示例为get_started/try_out→index.html#getting-started避免已有引用失效Windows 用户使用 docs/make.bat 代替make参数用法一致版本与版权文档站版本号始终来自仓库根VERSION文件页脚版权年份在conf.py中硬编码为 2025-2026更新年份需随发布周期手动修改该配置。九、小结TileLang 的文档体系以 docs/README.md 的三步流程pip3 install -r requirements.txt→make html→http.server预览为基础操作其工程实质是以docs/conf.py为中枢用 furo 主题 MyST Markdown 承载手写教程与编程指南用 sphinx-autoapi 从 tilelang 源码包自动生成 API 参考再由 maint/scripts/build_docs.sh 与 .github/workflows/publish-docs.yml 构成的 CI 链路在每次合入 main 后自动重建并推送到独立的发布仓库最终以tilelang.com见 docs/CNAME对外提供服务。掌握了这套配置你就可以在本地完整复现文档站的构建、预览与发布全过程。【免费下载链接】tilelangDomain-specific language designed to streamline the development of high-performance GPU/CPU/Accelerators kernels项目地址: https://gitcode.com/GitHub_Trending/ti/tilelang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考