围绕Sphinx搭建代码化的内容管理+文档开发系统 | 技术传播

【技术传播】这个话题荒废好久，今天“诈尸”一波。

话说这段时间学习和实践了一下开源工具Sphinx，实现了文档代码化开发和同源发布。在此之前，我一直以为部署一套这样的系统，非得采购专门工具不可；万万没想到，一个免费开源的工具，竟然可以做到如此交付水平；而且完全不需要开发者掌握专门的xml/dita格式，只需要配合通用性更高的rst/md格式，就可以轻松搞定内容开发——实在让人有种莫名“想跪”的冲动。港真，这种震撼，绝不亚于当初Obsidian带给我的感受。

不仅如此，后来我还发现，原来像英伟达、寒武纪这种体量的巨贵和新贵公司，也在使用Sphinx发布技术文档，看来这次是找对路子了。

从英伟达和寒武纪对外发布的技术文档，可以清楚地看到，它们都是应用了Sphinx和RTD主题

那么，今天就来简单总结复盘一下，希望给到有需要、感兴趣的朋友一点点启发。

什么是Sphinx？Sphinx，是一个基于Python，开源免费的文档生成工具。默认支持reStructuredText格式内容源码；通过第三方插件支持MyST Markdown格式的内容源码；最终将内容源码发布为html、PDF、ePub、Texinfo、manual pages和plain text等多种目标文档格式。

Sphinx的基本使用逻辑非常简单：

1. 在Windows系统下借助Chocolatey在线安装Sphinx。
2. 执行【sphinx-quickstart】命令创建文档项目。
3. 根据实际开发场景，修改配置：
   • 如果使用Markdown语法编写技术文档，需通过recommonmark插件支持Markdown。
   • 如果期望获得比较好的Web文档发布效果，可以配置应用sphinx-rtd-them。
4. 使用VSCode编写内容源码，包括node和index。
5. 执行发布命令，或者运行发布脚本，即可发布为多种目标格式的文档，如Web或PDF。

考虑到文章篇幅不宜过长，具体实施落地的操作方法就不展开说明了。网上有很多相关教程，操作不是很复杂；或者，也可以联系我私聊。

围绕Sphinx构建整个内容管理、文档开发和系统集成，几乎可以完全参照代码开发的系统构建：

• 使用VSCode进行源码编写；
• 使用Git进行内容和版本管理；
• 使用Sphinx进行文档发布；
• 使用Jenkins进行自动化部署。

在这里，只有一点需要特别说明的是：

如果想对Sphinx直出的PDF进行一定人工干预，如添加企业LOGO，或者应用自定义样式之类，那么，从源码到PDF之间，可以被编辑的中间文件，并不是我们所熟悉的Word，而是Latex。

Latex，是一种基于TeX，开源免费的排版系统，广泛应用于学术界和科技领域的文档编写。对于之前从来没有使用过Latex的开发者而言，前期势必会引入一些学习成本；但由于Latex同样是一种代码化的开发方式，在完成基本的模板设计后，完全可以通过Jenkins部署自动化地实现干预。

想象一下，当你只需聚焦在内容源码开发，后续的文档构建、文档优化、文档发布，以及系统集成，全部交由一个“自动化工厂”来实现，将会是何等美妙的未来。

今天的分享就是这些内容。

最后，让我们一起，感恩开源；有幸站在巨人的肩膀上，探索实现一个内容生产与消费的自动化工厂。