大家好，我是对“狗屁工作”本能感到厌烦和抵触，在AI的加持下，迫切想要找到方法解决的技术传播者睿齐。

说明

狗屁工作”（Bullshit Jobs）是已故人类学家大卫·格雷伯（David Graeber）在其2013年的同名著作中提出的概念，指那些本质上毫无意义、甚至有害，连从事者自己都无法证明其存在必要性的有偿工作。格雷伯认为，这类工作不仅无法创造社会价值，还会对从业者造成深层的心理伤害。

各位使用开源工具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理解目录结构，确保操作使用相对路径，且正确；

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

说明

例如，将html发布包压缩为.zip包时，可以优先考虑检索并调用当前系统中已有的压缩工具；而不是在自动化脚本中自行实现功能。

根据个人实践，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. 输入指令：

请帮我生成1个python脚本，用于sphinx文档自动发布。

输入参数：
-dt：设置文档类型。all：指打印全部3个文档类型；c：指仅打印【系统用户指南】；op：指仅打印【运营平台用户指南】；app：指仅打印【应用平台用户指南】；默认取值为all；
-ft：设置目标生成的文档类型。all：指同时发布latexpdf和html文档；html：指仅生成html文档；latexpdf指仅生成latexpdf文档；默认取值为all；

功能要求：

- 参考提供的bat文件，实现主要功能；
- 涉及的文件和目录操作，请参考当前工程，使用相对路径；
- 发布后的【文档名称】和【版本号】，请从对应的配置文件conf.py中获取，并保持一致；
    - 文档名称：对应conf.py文件中的【project】
    - 版本号： 对应conf.py文件中的【release】

- 压缩工具从当前系统中检索获取，不要在代码中指定；
- 脚本应支持在Windows和Ubuntu系统中执行；
- 请使用UTF-8编码，并注意避免可能出现的编码错误；
- 文档编译过程中，如果出现Error或者Warning，则打印到builddlog.txt文件中。

编码要求：

- 请在代码中添加必要的错误处理，确保代码健壮；
- 请在出现异常时，输出必要错误说明，帮助排查问题；
- 由于脚本涉及编译操作，执行时间较长，请给出必要进度说明，避免出现假死状态。

输出：builddoc.py

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

执行效果：

作为文档工程师，日常工作中无可避免地被各种类似的“狗屁时刻”所折磨，既耗

费时间，又无法获得认可和理解，还不得不做。未来，希望在AI的加持下，我们都可以获得“狗屁”自由。

今天的分享，就是这些内容。如果你喜欢这篇文章，觉得对你有所启发和帮助，记得点赞和分享；如果对有啥想法，或者问题想要交流，就留言告诉我吧。

其他推荐：

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

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

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

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

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

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

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

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

转战新媒体 | 技术传播

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

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

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

睿齐

技术传播者

自由摄影师

知识管理实践教练

品牌内容策划

汪力迪

公众号：techcomm / htstory

微信号：bgrichi 

邮箱：hash_0813@163.com