Search code examples
githubgithub-pagespython-sphinxread-the-docs

Github Pages with Sphinx generated documentation not displaying HTML correctly

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:

html as it appears in githubpages - missing all the customisation

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:

HTML as it appears locally on browser with all the required customization

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.

Solution

  • 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)