Github Pages with Sphinx generated documentation not displaying HTML correctly

Question

I have been trying to publish a Sphinx generated documentation for our repository on Github pages with the theme provided by readthedocs.org.

After a few attempts I managed to get it online by uploading the Sphinx generated HTML files in the gh-pages branch of the repository.

Obtaining this:

https://takeqontrol.github.io/qontrol_api/

Which is looking awful, erasing all the customization of the theme by Read the Docs.

Here is an example of what you see if you open the link:

But if I open those HTML files on my computer the pages looks exactly how I wanted them to look. Here is an example of how exactly the same HTML looks locally:

Does anybody know what is going on? Or even point me somewhere where I can find an explanation?

All the code is available here: https://github.com/takeqontrol/qontrol_api in the two branches.

Anastaciaanastas

Does this answer your question? Using github actions to publish documentation – Elmiraelmo

Unfortunately not. Thanks anyway. – Anastaciaanastas

In case it helps, I found a different solution that I posted here – Leland

Answer 1

I fought with this for 9 hours before figuring out that the underscore in the _static folder was causing the issue.

You need to bypass Jekyll on github pages.

To do this, add an empty .nojekyll to your gh-pages branch. (See example)

Badmouth

An empty .nojekyll file don't you mean? This also worked for me under a docs folder if I told GitHub Pages to use /docs as the source to publish from. – President

The sphinx.ext.githubpages Sphinx extension seems to help automate this. – Niersteiner

You saved me a lot of trouble, I had the same issue and this fixed it. Many thanks! – Hustler

Answer 2

I was having a similar issue and then found this, which solved it for me:

Python Sphinx css not working on github pages

Looks like using underscores for the _sources + _static folder caused the issues. Need to rename the folders and paths using them in the html files accordingly.

Woodyard

Hi Scott, thanks for your answer I tried doing that and now the page is not showing anymore. I get only the 404 error page not found. Still locally I can visualise the webpage perfectly. – Anastaciaanastas