如何将Sphinx/RST项目与外部表格/数据库关联同步？

一、让Sphinx直接拉取Google Sheets数据实现同步 #

完全可以实现自动同步，核心思路是将Google Sheets数据导出为可解析格式，再让Sphinx在构建时自动拉取并转换为RST内容：

1. 导出Google Sheets为可访问的CSV

   • 公开表格可直接生成CSV导出链接：格式为https://docs.google.com/spreadsheets/d/<表格ID>/export?format=csv&gid=<工作表ID>（工作表ID可从表格URL的gid=参数获取）。
   • 私有表格可通过Google Cloud创建服务账号，授权访问表格后用API获取CSV内容，避免公开链接的权限风险。

2. 在Sphinx构建流程中集成数据拉取与转换

   • 方式1：前置脚本+内置指令
     在项目Makefile中添加前置步骤，先拉取CSV到本地：

     sphinx-build:
         curl -o source/recipes.csv "https://your-csv-export-url"
         sphinx-build -b html source build/html
     

     随后在RST文档中用内置指令引用本地CSV：

     .. csv-table:: 餐厅食谱列表
        :header-rows: 1
        :file: recipes.csv
     

   • 方式2：自定义Sphinx扩展
     编写简单扩展，在Sphinx构建初始化阶段（builder-inited钩子）拉取CSV，调用csv2rst类库转换为RST片段并插入指定文档位置，适合需要对数据做过滤、排序等预处理的场景。

二、更适配Sphinx的存储方案 #

如果Google Sheets的同步维护成本较高，可考虑以下贴合Sphinx工作流的方案：

• Git托管的Markdown/RST文件
  让维护者直接编辑MD或RST格式的食谱文件，提交到Git仓库。Sphinx可直接读取这些文件构建，同步完全依赖Git版本控制，历史记录清晰，无需额外工具，适合有基础Git操作能力的维护人员。

• Git托管的CSV文件
  维护者用Excel、Numbers等工具编辑CSV格式的食谱，保存后提交到Git。Sphinx通过csv-table指令直接渲染内容，既兼顾维护者的易用性（无需学习标记语言），又能保证与Sphinx的适配性，版本回溯也方便。

• SQLite轻量数据库
  若食谱数量多、需要复杂分类/筛选逻辑，可将数据存储在SQLite中。编写Sphinx扩展，在构建时查询数据库并动态生成符合格式的RST内容，适合批量处理、动态生成内容的场景。

• Headless可视化CMS
  部署Netlify CMS这类无界面CMS，给维护者提供可视化的食谱编辑界面，后台自动将内容保存为MD/RST文件并提交到Git。既降低维护者的技术门槛，又能让Sphinx直接读取文件构建，同步无缝。

内容的提问来源于stack exchange，提问作者Zach