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

本文主要是介绍围绕Sphinx搭建代码化的内容管理+文档开发系统 | 技术传播,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

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

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

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

c4c48182523ed9a6ac2dd496e25f4df9.png

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

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

4263bf6a15edc415934a6bfdc7aae947.png

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

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

9b1b40765ab95bdbc3c170a6c8419a33.png

  1. 在Windows系统下借助Chocolatey在线安装Sphinx。

  2. 执行【sphinx-quickstart】命令创建文档项目。

  3. 根据实际开发场景,修改配置:

  • 如果使用Markdown语法编写技术文档,需通过recommonmark插件支持Markdown。

  • 如果期望获得比较好的Web文档发布效果,可以配置应用sphinx-rtd-them。

使用VSCode编写内容源码,包括node和index。

执行发布命令,或者运行发布脚本,即可发布为多种目标格式的文档,如Web或PDF。

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

8df569d63449c003361983e224e942cf.png

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

f41798c83ecddc97bb61b0956f5f2827.png

  • 使用VSCode进行源码编写;

  • 使用Git进行内容和版本管理;

  • 使用Sphinx进行文档发布;

  • 使用Jenkins进行自动化部署。

在这里,只有一点需要特别说明的是:

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

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

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

d4316093e27c0bb1a54475498c31d3fd.jpeg

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

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

其他推荐:

实施:GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

23f4a5c02c915549ec71de96673bc030.jpeg

技术传播是一片蓝海 | 技术传播

访谈:TC无处不在,只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了,你们还有我 | 技术传播

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测:王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

企业级信息管理系统初创方案构思 | 技术传播

 8160dfa4a4ed16dcc828e1a73bc0fafe.png

睿齐

技术传播者

自由摄影师

知识管理实践教练

品牌内容策划

汪力迪

公众号:techcomm / htstory

微信号:bgrichi

邮箱:hash_0813@163.com

392419eaf1eb406fc42534f061a19ef0.jpeg

这篇关于围绕Sphinx搭建代码化的内容管理+文档开发系统 | 技术传播的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!


原文地址:
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.chinasem.cn/article/1022205

相关文章

Linux系统中查询JDK安装目录的几种常用方法

《Linux系统中查询JDK安装目录的几种常用方法》:本文主要介绍Linux系统中查询JDK安装目录的几种常用方法,方法分别是通过update-alternatives、Java命令、环境变量及目... 目录方法 1:通过update-alternatives查询(推荐)方法 2:检查所有已安装的 JDK方

springboot自定义注解RateLimiter限流注解技术文档详解

《springboot自定义注解RateLimiter限流注解技术文档详解》文章介绍了限流技术的概念、作用及实现方式,通过SpringAOP拦截方法、缓存存储计数器,结合注解、枚举、异常类等核心组件,... 目录什么是限流系统架构核心组件详解1. 限流注解 (@RateLimiter)2. 限流类型枚举 (

在macOS上安装jenv管理JDK版本的详细步骤

《在macOS上安装jenv管理JDK版本的详细步骤》jEnv是一个命令行工具,正如它的官网所宣称的那样,它是来让你忘记怎么配置JAVA_HOME环境变量的神队友,:本文主要介绍在macOS上安装... 目录前言安装 jenv添加 JDK 版本到 jenv切换 JDK 版本总结前言China编程在开发 Java

Linux系统之lvcreate命令使用解读

《Linux系统之lvcreate命令使用解读》lvcreate是LVM中创建逻辑卷的核心命令,支持线性、条带化、RAID、镜像、快照、瘦池和缓存池等多种类型,实现灵活存储资源管理,需注意空间分配、R... 目录lvcreate命令详解一、命令概述二、语法格式三、核心功能四、选项详解五、使用示例1. 创建逻

Spring Boot Actuator应用监控与管理的详细步骤

《SpringBootActuator应用监控与管理的详细步骤》SpringBootActuator是SpringBoot的监控工具,提供健康检查、性能指标、日志管理等核心功能,支持自定义和扩展端... 目录一、 Spring Boot Actuator 概述二、 集成 Spring Boot Actuat

Python实现PDF按页分割的技术指南

《Python实现PDF按页分割的技术指南》PDF文件处理是日常工作中的常见需求,特别是当我们需要将大型PDF文档拆分为多个部分时,下面我们就来看看如何使用Python创建一个灵活的PDF分割工具吧... 目录需求分析技术方案工具选择安装依赖完整代码实现使用说明基本用法示例命令输出示例技术亮点实际应用场景扩

MySQL多实例管理如何在一台主机上运行多个mysql

《MySQL多实例管理如何在一台主机上运行多个mysql》文章详解了在Linux主机上通过二进制方式安装MySQL多实例的步骤,涵盖端口配置、数据目录准备、初始化与启动流程,以及排错方法,适用于构建读... 目录一、什么是mysql多实例二、二进制方式安装MySQL1.获取二进制代码包2.安装基础依赖3.清

C#监听txt文档获取新数据方式

《C#监听txt文档获取新数据方式》文章介绍通过监听txt文件获取最新数据,并实现开机自启动、禁用窗口关闭按钮、阻止Ctrl+C中断及防止程序退出等功能,代码整合于主函数中,供参考学习... 目录前言一、监听txt文档增加数据二、其他功能1. 设置开机自启动2. 禁止控制台窗口关闭按钮3. 阻止Ctrl +

linux批量替换文件内容的实现方式

《linux批量替换文件内容的实现方式》本文总结了Linux中批量替换文件内容的几种方法,包括使用sed替换文件夹内所有文件、单个文件内容及逐行字符串,强调使用反引号和绝对路径,并分享个人经验供参考... 目录一、linux批量替换文件内容 二、替换文件内所有匹配的字符串 三、替换每一行中全部str1为st

从入门到精通详解LangChain加载HTML内容的全攻略

《从入门到精通详解LangChain加载HTML内容的全攻略》这篇文章主要为大家详细介绍了如何用LangChain优雅地处理HTML内容,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下... 目录引言:当大语言模型遇见html一、HTML加载器为什么需要专门的HTML加载器核心加载器对比表二