企业官网建设流程全解析

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 开篇即说明文档构建在 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 < 4：autoapi 3.x 依赖 astroid 做静态解析，这里显式限制< 4以保证兼容。
• furo：文档站的主题（conf.py中html_theme = "furo"）。
• myst-parser：支持以 Markdown（MyST）编写文档；index.md中大量使用的:::{toctree}语法即由它解析。
• sphinx-reredirects：处理旧页面 URL 跳转（见下文重定向配置）。
• sphinx-tabs/sphinx-toolbox/sphinxcontrib_httpdomain：分别提供标签页、折叠块等 UI 组件与 HTTP 领域语法支持。
• fastapi+uvicorn：属于依赖清单中较特殊的成员，从依赖组合看应为构建/调试文档服务流程的辅助组件；文档主体渲染本身只依赖 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 = _build

• SPHINXBUILD固定使用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 = f"2025-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），同时兼容.rst；
• colon_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作为 Logo；
• docs/_static/custom.css 为在主题之上叠加的自定义样式；
• exclude_patterns中的_build防止构建产物递归进入源目录。

五、文档内容体系：index.md 的目录树

构建出的文档站结构由 docs/index.md 中的多个toctree块决定，当前线上文档分为以下板块（路径均相对于docs/目录）：

新增文档页面时，正确做法是：在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

这一方式只适合本地查看；由于构建产物是纯静态 HTML（Sphinxhtmlbuilder 输出），也可以直接双击index.html或在任意静态服务器中托管，CNAME 文件则用于声明正式发布域名。

七、CI 自动构建与发布流程

本地三步（装依赖 → 构建 → 预览）之上，仓库还配套了一条完整的 CI 发布链路，适合想理解“文档站如何保持与 main 分支同步”的读者。

7.1 构建脚本 build_docs.sh

maint/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组织下的仓库，且满足二者之一——
  1. pull_request_target事件，PR 状态为 closed 且merged == true、目标分支为main；
  2. 手动触发workflow_dispatch。 即：只有合入 main 分支的 PR 才会自动重新发布文档；
• 运行环境：runs-on: [self-hosted, nvidia]，自建 runner，Python 版本固定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 代码仓库解耦，发布失败不会回滚代码，且可以独立控制站点的静态托管。

八、实操要点与常见注意事项

结合上述配置，本地构建文档站时建议注意以下事项：

1. 必须在docs/目录内执行make html：Makefile 的SOURCEDIR = .依赖当前工作目录，而conf.py中autoapi_dirs = ["../tilelang"]等相对路径也是以docs/为基准解析的；
2. autoapi 锁定了sphinx-autoapi == 3.6.0与astroid < 4，升级 Sphinx 或相关生态包时可能触发兼容问题，遇到生成异常可先回到该版本组合；
3. 增量构建异常时用make clean：clean会同时删除_build与autoapi生成目录，再重新make html可解决 API 页面残留或目录树不同步的问题；
4. README.md不会出现在文档站中：exclude_patterns显式排除了它，它是构建指南而非文档页；
5. 旧链接维护：迁移或重命名页面后，应在conf.py的redirects中登记映射（现有示例为get_started/try_out→index.html#getting-started），避免已有引用失效；
6. Windows 用户使用 docs/make.bat 代替make，参数用法一致；
7. 版本与版权：文档站版本号始终来自仓库根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