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.

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 by pass Jekyll on github pages.

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