python sphinx-rtd-theme

# 从日常文档到专业站点：Python Sphinx RTD Theme 的深度实践

大概在两三年前，我接手了一个内部工具库的文档维护工作。那个项目用的是原生的Sphinx主题，坦白说，每次打开生成的HTML页面，都感觉回到了2005年——内容没问题，但视觉上总让人觉得这项目已经没人维护了。直到我换上了Read the Docs主题，整个项目团队的反馈都变了，连产品经理都开始主动看技术文档了。

这个经历让我意识到，一个好的文档主题，有时候比文档本身更能传达项目的品质感。

它到底是什么

Sphinx-rtd-theme（全称 sphinx_rtd_theme）本质上是一个Sphinx的扩展主题。Sphinx本身是个强大的文档生成器，能把reStructuredText或Markdown文件转换成HTML、PDF等格式。但这个默认的主题，坦白说，长得像技术手册的复印件——功能齐全，但谈不上好看。

这个主题直接复用了Read the Docs平台的视觉风格。Read the Docs是目前最流行的文档托管平台之一，无数知名项目的文档都托管在那里。所以当你用这个主题时，你的文档会自动获得类似网络效应——用户看到侧边栏、顶部导航、搜索框这些熟悉的元素，会本能地觉得这是个正经的、维护良好的项目。

我特别喜欢它的响应式设计。在手机上看Sphinx默认主题的文档，基本就是在折磨眼睛。但rtd主题的侧边栏会自动折叠，内容区域自适应，至少在通勤路上还能舒服地查个API。

它能做什么

除了让文档变好看，这个主题其实解决了好几个实际问题。

首先是导航问题。大多数项目文档的最大痛点就是用户找不到想看的内容。rtd主题默认带有可折叠的侧边栏导航，支持多级嵌套。用户可以直接在侧边栏中展开/收缩章节，比翻页式的阅读体验好得多。我曾经监控过项目的文档访问量，换上rtd主题后，页面的平均访问深度增加了将近40%——用户愿意在文档里多转转了。

其次是版本管理。如果你的项目需要维护多个版本的文档（比如v1.0、v2.0），这个主题提供了版本选择器。用户可以在不同版本之间切换，而不会搞混当前看的是哪个版本的文档。对于还在快速迭代的开源项目来说，这功能简直是救命稻草。

搜索功能也值得提。rtd主题内置了一个基于JavaScript的搜索框，支持模糊匹配。没有它的话，用户得用浏览器自带的Ctrl+F在整个页面上找，那体验完全不是一个级别。

另外它还支持自定义样式。但老实说，绝大部分项目根本不需要改太多。我见过有些团队把颜色和字体改得面目全非，反而破坏了文档的整洁感。保持默认风格，专注于内容，通常是最好的选择。

怎么在项目里用起来

安装很简单，一行命令搞定：

pipinstallsphinx-rtd-theme

然后在你项目的conf.py文件里，找到这样两行：

importsphinx_rtd_theme extensions=['sphinx_rtd_theme']html_theme='sphinx_rtd_theme'

这就完成了。运行make html重新生成文档，就能看到效果了。

不过有个细节很多人会忽略。如果你的项目同时配置了html_theme_path，要确保路径设置正确。我曾经犯过一个错，同时在两个地方指定了主题路径，结果生成的文档用了旧版本的主题，侧边栏总是渲染不对。排查了半天才发现是路径覆盖的问题。

对于新手，我建议直接从Read the Docs文档模板开始。在GitHub上搜readthedocs/sphinx_rtd_theme，仓库里有个demo目录，里面有一个完整的文档项目结构。直接复制过来改内容，比自己从零搭建要快得多。

我在项目中踩过的坑和推荐的玩法

先说配置。rtd主题有一些隐藏的配置项，可以让文档体验上升一个档次。比如html_theme_options里可以设置：

html_theme_options={'collapse_navigation':False,'sticky_navigation':True,'navigation_depth':4,'includehidden':True,'titles_only':False}

collapse_navigation默认是True，意味着用户进入一个页面后，侧边栏只展开当前章节。如果项目文档层次深、用户经常跨章节跳转，建议设为False，让所有层级都展开。另外sticky_navigation让侧边栏随页面滚动固定，用户在读长文档时不会丢失导航位置。

还有一个容易被忽略的功能是html_logo和html_favicon。很多项目只加了logo，忘了favicon。这个细节在用户把文档页面加入浏览器书签时特别有用——一个醒目的图标比一堆文字更容易辨认。

关于多版本文档，我的做法是在仓库里创建docs/目录，用标签（tag）来标记版本的文档快照。然后用Read the Docs平台自动构建每个标签的文档。本地开发时，rtd主题会自动适配当前版本，不需要额外配置。Release操作时，只需要打tag并推送，文档自动就生成了。

使用过程中最让我头疼的是自定义模板。如果你需要在所有页面底部加一个"联系我们"的链接，原生的rtd主题不提供这种配置项。解决方案是创建_templates/目录，在里面放一个layout.html文件：

{% extends "!layout.html" %} {% block footer %}<divclass="custom-footer"><ahref="mailto:support@example.com">需要帮助？联系我们</a></div>{{ super() }} {% endblock %}

这种方法虽然可行，但需要了解Jinja2模板引擎。我通常建议尽量避免这种定制，除非确实有强烈需求。否则升级主题版本时，这个模板很可能就冲突了。

和其他主题的较量

市面上还有几个常见的选择。Alabaster是Sphinx的默认主题，轻量、简洁、加载快。对于只需要一个README级别的文档的项目，alabaster完全够用，而且不需要安装额外依赖。但一旦文档规模上来，层次多了，侧边栏的劣势就会显现——alabaster默认不带可折叠导航，用户需要自己点开所有子目录，体验比较差。

另一个是Furo，一个相对较新的主题，最近在Python社区里挺火。它的设计更现代，支持浅色/深色模式自动切换。而且对移动端的适配做得更好，在手机上阅读文档时，Furo的中文排版比rtd要舒服一些。如果你的项目主要是给开发者用的，且文档以代码示例居多，Furo会是个不错的选择。

但Furo最大的问题是社区支持。rtd主题作为Read the Docs的默认主题，背后有整个平台团队维护。出了问题，在GitHub上提issue通常几小时内就有回复。Furo的维护者相对较少，有些小bug需要等待较长时间。

还有Material for MkDocs，这是另一个文档系统（MkDocs）的主题。如果你主要在写Python且项目规模较大，选Sphinx更合适，因为Sphinx对Python代码的分析和自动文档生成能力更强。MkDocs的优势在轻量，适合内容主导的文档，比如社区维基或操作手册。两个工具生态不同，迁移也不容易。

做个简单的决策思路：项目文档需要自动生成API文档吗？需要版本管理吗？如果都选"是"，那就用Sphinx + rtd主题，这是最成熟、最稳妥的方案。如果只是写纯文本的文档，不需要代码分析，MkDocs + material主题会更快地落地。

以我个人的经验，对于大多数Python项目，rtd主题是最没有学习成本的选择。用户熟悉、搜索引擎友好、维护简单。当团队里每个人都觉得"文档难看"而去翻它的时候，你就知道这次选对了。