AI辅助编程:Sphinx文档工程自动化发布脚本

各位使用开源工具Sphinx进行文档开发和发布的伙伴，你是否也曾有过，或正在经历着，与我类似的困境：为了发布并归档html和latexpdf文档各一，不得不进行这样一系列操作：

1. 在Sphinx文档工程目录：执行make html命令发布html文档；

2. 进入build目录：

1. 将html文档包改名为上线后的目标名称；

2. 将html文档包压缩为.zip包；

3. 将.zip包改名为规范命名；

4. 将.zip文件归档至目标目录。

3. 返回Sphinx文档工程目录：执行make latexpdf命令发布latexpdf文档；

4. 进入build/latexpdf目录：

1. 将latexpdf文档改名为规范命名。

2. 将latexpdf文档归档至目标目录。

看到这里，是不是感觉整个人都不好了？

这里提到的一些文件/目录操作，很可能还只是你日常工作中的冰山一角，如果——我是说“如果”——Sphinx文档工程目录下不只包含了1本文档，而是好几本文档，都需要发布，请问阁下该当如何应对？

好了，让我们收敛一下发散的思路，回到问题的本质。

在使用sphinx工具手动发布文档时，可能遇到以下问题：

1）频繁涉及文档/目录操作：

• 按命名规范，修改目录名称

• 按命名规范，修改文件名称

• 将html目录压缩为zip包

• 将文件从发布目录中复制到指定目录中进行归档等

2）如果当前源码库中，同时包含多个文档（或文档版本）：

• 在存储时，为了避免同名覆盖，对index和conf文件改名区分；

• 在编译时，需要将改名后的index和conf文件修改为标准名称。

这就是我们在使用Sphinx工具进行文档发布时遭遇到的“狗屁”时刻。

有没有一种可能，只需要输入一条指令，就可以帮我完成这一系列的“狗屁”操作？

有，试试用AI辅助编程吧，手搓一个Sphinx文档工程自动化发布脚本。

1）考虑到自动化脚本应兼容适用于Windows系统和Ubuntu系统进行文档编译，因此推荐采用Python语言进行脚本开发。

2）考虑到自动化脚本应兼容适用于所有文档工程，因此可以从Sphinx文档工程的conf.py文件中获取文档信息，如【project（文档名称）】或【release（版本号）】，用于设置文件名。

3）使用AI辅助编程工具（如Cursor）：

• 提供文档工程目录，便于AI理解目录结构，确保操作使用相对路径，且正确；

• 给出指令说明要求，需要考虑【输入接口】和【系统环境】，避免硬编码到脚本中。

根据个人实践，Cursor输出的Python脚本，基本可以较高水平地实现功能；后续实际应用中如果遇到问题，再迭代改进。

在这个示例中：

1）Sphinx文档工程共包含3个文档；

2）自动化发布脚本包含2个输入参数：

• 可指定发布的文档，或默认为发布所有文档；

• 可指定发布的文档类型（html/latexpdf），或默认为同时发布2种文档；

3）html文档：打包为.zip文件，并按指定规则命名；

4）latexpdf文档：按指定规则命名；

5）将html文档和latexpdf文档归档至指定目录。

也就是说，执行自动化发布脚本，在默认情况下，最多可同时发布并归档6个文档。

操作说明

由于我最初是尝试使用Windows系统下的批处理脚本（.bat）来解决文档自动化发布问题，所以还是手搓了一些执行脚本。

后来考虑到很多时候需要远程登录到Ubuntu系统上进行文档编译，Windows系统下开发的.bat脚本并不适用Ubuntu系统，所以改用Python语言。

不过之前手搓的.bat脚本，可以作为AI辅助编程的输入，精确地描述操作流程。

AI辅助编程

输入：

1. 提供包含文件/目录操作流程的.bat文件；

2. 提供Sphinx文档工程目录路径；

3. 输入指令：

输出：Cursor输出的代码质量很高，基本上无需调试，直接可用。

其他推荐：