Sphinx docs displaying locally but not at URL when pushed to GitHub

Question

I generated Python docs using Sphinx using make html. When I opened index.html in my browser the docs displayed as expected and all links worked as expected.

I then committed all docs and pushed to a branch in GitHub.

When I access the url https://<my company>.github.io/<my repo>/ the page displays but the CSS isn't working and some of the links do not work. Does anybody know why this might be?

Answer 1

The problem was that some files were missing. After reading this I added an empty .nojekyll which resolved the issue.

Answer 2

The reason for this might be that some files like _static and _sources are missing from the directory that contains index.html file. By default, Jekyll ignores directories starting with _. Adding .nojekyll will signal to GitHub Pages to not use Jekyll for building your site, and hence it will not ignore files like _static and _sources directories.

If you want to use sphinx-build and copy the html files to another branch like gh-pages, you can use a setup like below:

- name: Build Sphinx documentation
  run: |
    cd docs
    sphinx-build . build  
    touch build/.nojekyll

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./docs/build/
    publish_branch: gh-pages
    destination_dir: docs

In my case, I was missing the touch build/.nojekyll part and thus the _static and _sources directories were missing.