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?
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.