Sphinx + Read the Docs 文档平台构建

构建这个平台主要是从学弟那里了解到Sphinx + RTD构建在线文档很方便且好维护，所以硬是挤出了些时间来试着玩了玩这个东西。

一句话来总结，这个项目就是先用 Sphinx 生成文档，然后用 GitHub 托管文档，再导入到 Read the Docs 生成在线文档，具体效果如图所示（链接在此）。

如何部署可以参考入门教程。

碎碎念

我想部署这个玩意的需求在于前段时间组里有同学在尝试用ollama部署开源模型，然而这个活我之前就做过。我就在想要是我当时做的时候要是能顺便记录一份笔记或者教程，到时候后来的同学就可以直接根据这个教程来run了，省去很多学习成本。

当然这个思路不管是我还是实验室之前都有做过，比如我做的这个博客网站，里面有些自己瞎折腾的一些技术实现；狗哥之前也搞过一个语雀团队来分享我们读过的论文。但是如果说需要做一个分享平台来供组内同学交流，博客显然有点不够看，语雀虽说可以，但是有人数限制（10人，超过了就得氪金），且没法上传大文件（单文件超过30MB），文件类型和存储空间有限制（压缩包不行）。

Sphinx + RTD在配置一番后可以做到基于Github PR进行文档上传与分享（理论上团队人数无限制），基于阿里云OSS（实际上随便一个云服务都可以）管理文件、大文件随意上传（40GB云存储空间仅需18元/年），诚意满满。最重要的是不需要登录之类的操作就可以查看对应文档，很省心。当然缺点也是有的，那就是需要一定的学习门槛，至少得了解markdown文档怎么写，想要插图片得配置一下PicGo，上传文件还得使用脚本上传，没有像语雀那种所见即所得的方便。但是考虑到这个价位，能有这么多就很不错了。

技术分解

Sphinx

Sphinx是一个文档生成器，主要基于reStructuredText(.rst)语言，也支持Markdown语言扩展，相比Hexo这种构建博客的生成器来说，结构化能力更强，可以支持复杂的交叉引用，并且支持从代码中一键生成文档（基于docstring），就我短短一两天的使用体验来看，它的目录导航可以做的很干净漂亮。同时rst语言也有些自己的小语法糖，例如:doc:可以直接引用文章，:toctree:可以生成结构化的目录等等，但是和hexo相比暂时无法判断是否更方便（hexo也有自己的语法糖，而且这方面两者我了解的都不多）。

Read the Docs (RTD)

RTD主要就是一个文档托管和自动构建平台了，和Vercel挺像，都是从Github上爬项目，然后在自己平台部署供用户查看，但是好像只能访问公共项目，不知道是不是访问私有项目这个功能需要充钱才行，感觉这也是一个缺点。

技术集成逻辑

源码（.py/.rst/.md） + 配置（conf.py） → Sphinx → HTML文档 → RTD托管展示

1. 本地或 RTD 上 Sphinx 读取 conf.py
2. 根据 .rst 或 .md 文件生成文档结构
3. 输出 HTML 页面（或 PDF 等）
4. RTD 自动部署并生成一个在线文档站点

参考

入门教程

Sphinx + Read the Docs 从懵逼到入门

官方文档

Sphinx

Read The Docs

可以对比这个demo页面以及实现源码来快速了解Sphinx中一些样式的实现方式，比看文档更快。

Sphinx主题

官方主题展示平台：Sphinx Themes Gallery

个人比较喜欢这个：Awesome

我搭建的平台

平台、Github项目