企业官网建设流程全解析

• 机器学习
• 深度学习
• AutoML
• 大数据
• 后端

本篇技术指南以 h2o-3 仓库内置的 h2o-docs-theme/README.rst 为核心，围绕 H2O 开源机器学习平台文档所采用的 sphinx_rtd_theme（Read the Docs Sphinx 主题）展开。你将掌握如何通过 pip 包或源码目录两种方式接入该主题、在conf.py中完成主题与粘性导航配置、理解左侧目录（TOC）的构建机制，以及如何使用 SASS + Grunt 的完整前端工具链修改主题样式并产出可发布的压缩版本。

主题是什么：h2o-3 中的 Read the Docs Sphinx 主题

sphinx_rtd_theme是一个为 Sphinx 文档系统设计的移动端友好（mobile-friendly）原型主题，最初面向 readthedocs.org 站点开发。在 h2o-3 仓库中，它以独立的h2o-docs-theme/目录形式被完整携带，作为 H2O 文档站点的主题来源。

整个主题是一个以 SASS 为主要开发语言的工程：源码样式位于 sass/ 目录，由 Bower 管理前端依赖（包括 wyrm、bourbon、neat、font-awesome），再通过 Grunt 编译为可直接被 Sphinx 使用的 CSS 产物。运行时所需的模板与静态资源则放在 sphinx_rtd_theme/ 目录中，具体包含：

• Jinja2 模板：layout.html、breadcrumbs.html、footer.html、searchbox.html、versions.html、search.html等；
• 编译产物：static/css/theme.css 与 static/css/badge_only.css；
• 前端交互脚本：static/js/theme.js；
• 图标字体：static/fonts/下的 FontAwesome 系列字体文件；
• 主题声明文件：theme.conf。

主题本身通过 setup.py 打包发布，其package_data明确声明了theme.conf、所有*.html模板、static/css/*.css、static/js/*.js与static/font/*.*作为包内资源，因此pip install后主题文件会随 Python 包一同安装。

仓库中还内置了一套演示文档（demo_docs/source/index.rst），包含 toctree、数学公式（mathjax）、autodoc API 测试、巨型表格、admonition 提示框、代码高亮、侧边栏、引用等典型 Sphinx 元素，用于在开发主题时即时验证渲染效果。

安装与集成：两种接入方式

主题指南给出了两条接入路径，可根据你的项目环境选择。

方式一：通过 pip 包安装

将包添加到requirements.txt后安装：

$ pip install sphinx_rtd_theme

然后在 Sphinx 的conf.py中引入并指定主题：

import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

get_html_theme_path()返回主题包在 Python 环境中的实际安装路径，Sphinx 通过html_theme_path定位到该路径下的theme.conf与模板目录。仓库中 requirements.txt 声明了最小依赖sphinx>=1.1，这是主题正常工作所需的 Sphinx 版本下限。

方式二：通过 git 或直接下载（源码集成）

如果你需要直接修改主题源码（这正是 h2o-docs-theme 在仓库中内置的目的），可以把主题作为sphinx_rtd_theme/sphinx_rtd_theme目录，通过符号链接（symlink）或 subtree 方式挂载到你的文档目录docs/_themes/sphinx_rtd_theme下，然后在conf.py中添加两个设置：

html_theme = "sphinx_rtd_theme" html_theme_path = ["_themes", ]

此时 Sphinx 会从docs/_themes/下查找同名主题目录。h2o-docs-theme 的演示构建正是采用这种方式：演示文档的 conf.py 中设置了html_theme_path = ["../.."]，即相对demo_docs/source/向上两级，正好定位到仓库根目录下的h2o-docs-theme/，从而直接使用源码目录中的主题。

主题配置详解：conf.py 与 theme.conf

主题选项与粘性导航

主题允许通过conf.py的html_theme_options覆盖行为，核心可配项是sticky_navigation（粘性导航）。演示 conf.py 中给出了标准写法：

html_theme_options = { # 'sticky_navigation' : True # Set to False to disable the sticky nav while scrolling. }

而主题默认值定义在 theme.conf 中：

[theme] inherit = basic stylesheet = css/theme.css [options] typekit_id = hiw1hhg analytics_id = sticky_navigation = False

关键字段说明：

• inherit = basic：主题继承 Sphinx 内置的basic主题，在此之上叠加 RTD 风格的模板与样式；
• stylesheet = css/theme.css：默认加载的样式表；
• sticky_navigation = False：本仓库中默认关闭粘性导航；如需启用，在html_theme_options中显式设置为True即可。

粘性导航的前端逻辑位于 layout.html：当theme_sticky_navigation为真时，页面会调用SphinxRtdTheme.StickyNav.enable()（由static/js/theme.js提供实现）。启用后，侧边目录会在滚动时"吸附"（stick）在屏幕上；若目录内容过长超出可视区域，则会回退为静态定位。因此对章节繁多的大文档，粘性导航并非总是最优选择。

本地与 Read the Docs 双环境兼容

主题 README 特别指出一个坑：如果在本地构建时导入sphinx_rtd_theme并把同一份配置交给 Read the Docs 在线构建，RTD 会因重复加载主题而产生冲突。推荐的兼容写法是借助READTHEDOCS环境变量做环境探测：

# on_rtd is whether we are on readthedocs.org on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if not on_rtd: # only import and set the theme if we're building docs locally import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # otherwise, readthedocs.org uses their theme by default, so no need to specify it

即：本地构建时显式指定主题，RTD 上则交给平台默认处理。这个模式同样被应用在主题自身的模板中——layout.html 里通过{% if not READTHEDOCS %}判断，仅在非 RTD 构建时加载本地 CSS 与theme.js脚本，避免与 RTD 托管的静态资源冲突。

左侧目录（TOC）的构建机制

主题的左侧菜单完全由index.rst中定义的toctree(s)驱动，这是 Sphinx 文档导航的核心机制。在 layout.html 中可以看到具体实现：

<div class="wy-menu wy-menu-vertical"># 1. 在虚拟环境中安装 Sphinx pip install sphinx # 2. 安装 SASS（ruby 版） gem install sass # 3. 安装 node、bower 与 grunt # // Install node # brew install node # // Install bower and grunt npm install -g bower grunt-cli # 4. 安装主题自身的依赖（node 端） npm install

说明：brew install node适用于 macOS；Linux 发行版可改用对应的系统包管理器安装 node.js，随后执行npm install -g bower grunt-cli与npm install。

运行 grunt 默认任务

确保当前处于虚拟环境中，进入 h2o-docs-theme 目录执行：

grunt

根据 Gruntfile.js 的定义，默认任务default依次串联：exec:bower_update→clean:build→sass:dev→exec:build_sphinx→connect→open→watch，它会带来四件"值得为之折腾环境"的事情：

1. 安装并更新所有 bower 依赖（grunt-exec执行bower update），保证 wyrm 等 SASS 库可用；
2. 运行 Sphinx 构建新文档（exec:build_sphinx执行sphinx-build demo_docs/source demo_docs/build），在 demo_docs/build 目录产出演示 HTML；
3. 监听 SASS 文件变化并即时编译 CSS：sass:dev任务以expanded（未压缩、便于调试）风格把 sass/*.sass 编译到sphinx_rtd_theme/static/css/，watch任务持续监视sass/*.sass与bower_components/**/*.sass的改动；
4. 自动重建 Sphinx 文档并热刷新：watch同样监视sphinx_rtd_theme/**/*、demo_docs/**/*.rst与demo_docs/**/*.py，一旦发现.rst、.html、.js、.css文件变化就执行clean:build后重建文档；connect在localhost:1919起本地服务器（open会自动打开浏览器），livereload让浏览器实时刷新。

其中 SASS 的编译路径由sass:dev的loadPath指定（bourbon、neat、font-awesome、wyrm 各自的 SASS 目录），源码sass/*.sass经编译后输出到sphinx_rtd_theme/static/css并自动改为.css后缀。主题样式按职责拆分在多个 SASS 文件里，如 _theme_layout.sass（布局）、_theme_rst.sass（reST 元素样式）、_theme_variables.sass（变量）、_theme_badge.sass（徽标）以及入口文件 theme.sass 与 badge_only.sass。

提交 Pull Request 前：grunt build

开发完成并准备提交时，运行发布构建：

grunt build

build任务执行exec:bower_update→clean:build→sass:build→exec:build_sphinx：其中sass:build使用compressed（压缩）风格编译 CSS，clean:build会清空旧的demo_docs/build产物，最终产出清理了冗余文件、压缩了样式表的可分发包。README 明确要求：在发送 Pull Request 之前务必执行grunt build。

主题 TODO 与扩展方向

README 末尾列出主题的待办事项：将部分 SASS 变量提升到主题层级，以便使用者在主题层面直接覆盖基础配色（colors）。从源码结构看，_theme_variables.sass 已是主题变量的集中存放处，后续扩展配色只需从该文件入手即可。

与 H2O 文档工程的衔接

在 h2o-3 仓库中，h2o-docs-theme/目录以独立子工程形式内嵌于仓库根目录，与 h2o-docs 文档目录平行存在；h2o-docs-theme/sphinx_rtd_theme/中即为可直接被 Sphinxhtml_theme_path引用的主题实体。这意味着 H2O 文档团队可以在这个仓库内直接修改主题源码、通过demo_docs即时预览，再执行grunt build产出压缩产物供正式文档构建使用，形成"源码定制 → 演示验证 → 发布产物"的完整闭环。

参考要点速览

• 安装方式：pip install sphinx_rtd_theme（requirements.txt 要求sphinx>=1.1），或把主题目录放入html_theme_path；
• 核心配置：html_theme = "sphinx_rtd_theme"、html_theme_options['sticky_navigation']（默认关闭，定义于 theme.conf）；
• 目录构建：index.rst中的toctree驱动左侧菜单，默认 2 层深度、includehidden=true，无 toctree 时回退本地 toc（实现见 layout.html）；
• 开发流程：pip install sphinx+gem install sass+npm install -g bower grunt-cli+npm install，随后grunt开发、grunt build发布；
• 环境兼容：通过os.environ.get('READTHEDOCS') == 'True'区分本地构建与 RTD 在线构建，避免主题重复加载。

• 机器学习
• 深度学习
• AutoML
• 大数据
• 后端