PandocMissing when building Sphinx documentation

Question

I am working on using GitHub Actions to build and deploy some Sphinx documentation to GitHub pages and am running into a problem. When the action runs, I get the error:

Notebook error:
183
PandocMissing in examples/Admissions Data.ipynb:
184
Pandoc wasn't found.
185
Please check that pandoc is installed:
186
https://pandoc.org/installing.html
187
make: *** [Makefile:20: html] Error 2

This is very similar to this question Building docs fails due to missing pandoc, but when I try out the solutions outlined in these answers it does not fix the problem. Also, I am using Sphinx not read the docs.

My sphinx.yml file (according to the suggestion outlined in the deploying Sphinx docs online tutorial) is:

name: Sphinx build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - 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

Additionally, my requirements.txt file is:

furo==2021.11.16
nbsphinx
sphinx_gallery
sphinx_rtd_theme
markupsafe==2.0.1
geostates
geopandas
pandas
jinja2>=3.0
pypandoc

Clearly something is breaking here with the pandoc installation where I have .ipynb files tying to be converted into markdown files to be rendered in HTML. Does anyone have an insight into what the fix is here? I tried adding the code from the answer in the aforementioned question into my conf.py file but this did not fix the problem. I am thinking it might have to do with conda vs pip, but I am not sure how to fix this.

My repo for this testing project is available here where you can view the entire build error messages under the Actions tab.

Update: It seems like I need to do (possible) something related to adding some lines of code in the sphinx.yml file?

EDIT 9/1/22:

From reading the Pandoc tutorial online is says that something along the lines of:

name: Simple Usage

on: push

jobs:
  convert_via_pandoc:
    runs-on: ubuntu-18.04
    steps:
      - uses: docker://pandoc/core:2.9
        with:
          args: "--help" # gets appended to pandoc command

is how Pandoc is set up with GitHub Actions. The only thing is I am pretty confused about how to integrate this code into the sphinx.yml file (where and what code to copy over) and which commands to pass through as the arguments?

A guess: you need to add `pypandoc_binary` in requirements.txt. See https://pypi.org/project/pypandoc/ — mzjn, Aug 30 '22 at 15:19
@mzjn unfortunately this doesn't seem to fix the problem. It instead throws the error: `ERROR: No matching distribution found for pypandoc_binary` when this is added to the `requirements.txt` file — Ethan, Aug 30 '22 at 16:26
Thank you! I've included most details in the answer, so I'm deleting my other comments. — tarleb, Sep 06 '22 at 20:06

tarleb · Accepted Answer · 2022-09-06T20:10:38.470

The error happens in the ammaraskar/sphinx-action@master action. The action sets up it's own Docker container, so installing pandoc in the main runner will have no effect.

The docs of that action make it seem like it should be possible to install pandoc by setting an appropriate pre-build-command, e.g.,

    - name: Build HTML
      uses: ammaraskar/sphinx-action@master
      with:
        pre-build-command: >-
          apt-get update && apt-get install -y pandoc

However, this does not work; there is a pull requests that might fix this, but it hasn't been merged.

One possibility, that has also been noted in the comments by @mzjn, would be to use pypandoc_binary instead of pypandoc in file docs/requirements.txt. This would usually be the preferred solution. However, the versions used in the action image are rather old, so the installer cannot find a matching version, and the installer errors with a message that it "cannot find a matching distribution for pypandoc_binary".

It therefore seems like the only real option is to use a different action, or to fork and fix ammaraskar/sphinx-action. E.g., after forking the repository on GitHub, the action's Dockerfile can be changed to include a copy of pandoc:

COPY --from=pandoc/minimal:2.19.2 /pandoc /usr/bin/pandoc

Adding the above line somewhere in the middle of the Dockerfile will include a statically compiled pandoc binary in the imaged used to run the action.

The new action can be used by replacing ammaraskar/sphinx-action in sphinx.yml with the name of the new fork. Everything should run smoothly with that in place.

PandocMissing when building Sphinx documentation

1 Answers1

Linked