I am working on publishing some Sphinx documentation on Github pages using GitHub Actions.

Initially, I followed the Sphinx documentation generation tutorial to create my documentation files locally. Once I did this successfully, I got to the part of the tutorial for Deploying a Sphinx project online. Here is where I am a bit stuck. I am trying to use GitHub pages to display the HTML files for this project but am getting some errors.

To my understanding, in order to do this, I need to use GitHub Actions in order to build the Sphinx documentation so that the .rst files can be turned into HTML files and then these files can be deployed to the GitHub Pages site.

What I did first: I followed this portion of the tutorial and did three things:

1. Activated GitHub Pages on the repo online
2. Add a sphinx.yml file inside of a .github/workflows directory I created in the repo online
3. Added a requirments.txt files in the /docs subdirectory

According to the tutorial online, this is the contents of my sphinx.yml file online:

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

The content of my requirements.txt file:

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

The directory structure for my project online for the GitHub repo is the following:

.github/workflows
    sphinx.yml

docs
    _staic
    build
    examples
    source
    all the .rst files
    requirements.txt

project
    all the python files .py

README.md

My project and the repo are available here.

The problem is that every time I run the GitHub Actions the build/deploy step fail and the HTML files are not generated and not deployed to the GitHub Pages site. Consequently, when I click the link to the GitHub Pages page it results in a:

404 Error Page Not Found

The error for the build failure is pretty complex but is shown on the repo page under the Actions tab. I was wondering if anyone had any insight into what the problem is here or what might be happening. I think it might have something to do with the dependencies or perhaps the demo.yml file provided in the tutorial does not work correctly. A few causes might be that my project documentation is generated using an additional layer of complexity including using the autosummary and the nbsphinx packages.

EDIT 8/30/22:

Update: So following the excellent suggestion of Steve below, I have applied an iterative approach to installing each missing dependency by adding it to the requirements.txt file to slowly remove each of the subsequent errors. The thing that I am running into now is the following error:

Notebook error:
182
PandocMissing in examples/Admissions Data.ipynb:
183
Pandoc wasn't found.
184
Please check that pandoc is installed:
185
https://pandoc.org/installing.html

Which seems to be arising due to a mismatch with trying to convert one of my .ipynb files to markdown to render for the HTML files. After reading extensively this question it seems like there is some issue with using pip to install it.

I have read that pandocs requires something in the format 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

Do I just add this to my sphinx.yml file somewhere? If so where should this be put in and should all of the code be included?

CodePudding user response：

This error:

https://github.com/eolesinski/doctesting/runs/8076250971?check_suite_focus=true#step:4:64

Could not import extension nbsphinx (exception: No module named 'nbsphinx')

...means that you need to install the nbsphinx extension, and possibly other packages that you already installed in your local environment but did not tell GitHub Actions to also install. To remedy this, add the following to your requirements.txt:

nbsphinx

If you see similar errors again, then add the missing module to requirements.txt, and try again. Repeat as necessary.

Pandoc is a system requirement that cannot be installed via pip. For installing in GitHub Actions see https://pandoc.org/installing#github-actions.