使用GitHub Actions构建部署Sphinx文档时PandocMissing错误的解决及配置整合咨询

你遇到的核心问题是**ammaraskar/sphinx-action默认运行环境没有安装系统级的Pandoc**——虽然你在requirements.txt里添加了pypandoc，但它只是Python层的封装工具，必须依赖系统中存在的Pandoc二进制文件才能工作。下面是两种可行的解决方案，推荐第一种更简单的实现方式：

方案一：直接在Ubuntu环境中安装Pandoc #

Ubuntu官方软件源自带Pandoc，你只需要在运行Sphinx构建前新增一个安装步骤即可。修改后的完整sphinx.yml如下：

name: Sphinx build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      # 新增步骤：安装系统级Pandoc
      - name: Install Pandoc
        run: |
          sudo apt-get update
          sudo apt-get install -y pandoc
      - name: Build HTML
        uses: ammaraskar/sphinx-action@master
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: html-docs
          path: docs/build/html/
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/build/html

方案说明 #

• 新增的Install Pandoc步骤会在GitHub Actions的Ubuntu runner中直接安装Pandoc二进制文件，这样nbsphinx转换.ipynb文件时就能找到所需工具了。
• 不需要修改conf.py或依赖配置，因为问题本质是系统环境缺失工具，而非Sphinx的配置问题。

方案二：使用包含Pandoc的Docker镜像运行构建 #

如果你更倾向于用Docker隔离环境，可以修改sphinx-action的调用方式，指定包含Pandoc的基础镜像。这种方式步骤稍复杂，但环境隔离性更好：

name: Sphinx build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build HTML with Pandoc included
        uses: ammaraskar/sphinx-action@master
        with:
          # 在容器启动后先安装Pandoc
          pre-build-command: "apt-get update && apt-get install -y pandoc"
          # 指定使用Ubuntu基础镜像
          docker_image: "ubuntu:latest"
      # 后续上传和部署步骤保持不变
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: html-docs
          path: docs/build/html/
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/build/html

额外提示 #

你之前尝试将解决方案添加到conf.py中无效，是因为该文件是Sphinx的配置文件，无法解决系统级工具缺失的问题。必须在GitHub Actions的环境初始化阶段完成Pandoc的安装，才能让nbsphinx正常调用它完成.ipynb文件的转换。

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