【技术传播】这个话题荒废好久，今天“诈尸”一波。
话说这段时间学习和实践了一下开源工具Sphinx，实现了文档代码化开发和同源发布。在此之前，我一直以为部署一套这样的系统，非得采购专门工具不可；万万没想到，一个免费开源的工具，竟然可以做到如此交付水平；而且完全不需要开发者掌握专门的xml/dita格式，只需要配合通用性更高的rst/md格式，就可以轻松搞定内容开发——实在让人有种莫名“想跪”的冲动。港真，这种震撼，绝不亚于当初Obsidian带给我的感受。
不仅如此，后来我还发现，原来像英伟达、寒武纪这种体量的巨贵和新贵公司，也在使用Sphinx发布技术文档，看来这次是找对路子了。
从英伟达和寒武纪对外发布的技术文档，可以清楚地看到，它们都是应用了Sphinx和RTD主题
那么，今天就来简单总结复盘一下，希望给到有需要、感兴趣的朋友一点点启发。
什么是Sphinx？Sphinx，是一个基于Python，开源免费的文档生成工具。默认支持reStructuredText格式内容源码；通过第三方插件支持MyST Markdown格式的内容源码；最终将内容源码发布为html、PDF、ePub、Texinfo、manual pages和plain text等多种目标文档格式。
Sphinx的基本使用逻辑非常简单：
在Windows系统下借助Chocolatey在线安装Sphinx。
执行【sphinx-quickstart】命令创建文档项目。
根据实际开发场景，修改配置：
如果使用Markdown语法编写技术文档，需通过recommonmark插件支持Markdown。
如果期望获得比较好的Web文档发布效果，可以配置应用sphinx-rtd-them。
使用VSCode编写内容源码，包括node和index。
执行发布命令，或者运行发布脚本，即可发布为多种目标格式的文档，如Web或PDF。
考虑到文章篇幅不宜过长，具体实施落地的操作方法就不展开说明了。网上有很多相关教程，操作不是很复杂；或者，也可以联系我私聊。
围绕Sphinx构建整个内容管理、文档开发和系统集成，几乎可以完全参照代码开发的系统构建：
使用VSCode进行源码编写；
使用Git进行内容和版本管理；
使用Sphinx进行文档发布；
使用Jenkins进行自动化部署。
在这里，只有一点需要特别说明的是：
如果想对Sphinx直出的PDF进行一定人工干预，如添加企业LOGO，或者应用自定义样式之类，那么，从源码到PDF之间，可以被编辑的中间文件，并不是我们所熟悉的Word，而是Latex。
Latex，是一种基于TeX，开源免费的排版系统，广泛应用于学术界和科技领域的文档编写。对于之前从来没有使用过Latex的开发者而言，前期势必会引入一些学习成本；但由于Latex同样是一种代码化的开发方式，在完成基本的模板设计后，完全可以通过Jenkins部署自动化地实现干预。
想象一下，当你只需聚焦在内容源码开发，后续的文档构建、文档优化、文档发布，以及系统集成，全部交由一个“自动化工厂”来实现，将会是何等美妙的未来。
今天的分享就是这些内容。
最后，让我们一起，感恩开源；有幸站在巨人的肩膀上，探索实现一个内容生产与消费的自动化工厂。
其他推荐：
实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播者
自由摄影师
知识管理实践教练
品牌内容策划
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
邮箱：hash_0813@163.com
扫一扫
782
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
