CODEWITHSUNDEEP
githubgithub-pagespython-sphinxread-the-docs
Raf
Raf

Reputation: 343

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.

Upvotes: 23

Views: 5222

Answers (2)

K.S.
K.S.

Reputation: 3189

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)

Upvotes: 20

Scott
Scott

Reputation: 31

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.

Upvotes: 3

Related Questions