21

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Raf
  • 323
  • 2
  • 7
  • Does this answer your question? [Using github actions to publish documentation](https://stackoverflow.com/questions/57989790/using-github-actions-to-publish-documentation) – Steve Piercy Jun 28 '20 at 19:15
  • Unfortunately not. Thanks anyway. – Raf Jul 31 '20 at 08:00
  • In case it helps, I found a different solution that I posted [here](https://stackoverflow.com/a/65581149/6942666) – Eric Wiener Jan 05 '21 at 14:48

2 Answers2

15

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)

K.S.
  • 2,846
  • 4
  • 24
  • 32
  • 1
    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. – snark Feb 18 '21 at 15:05
  • 2
    The [`sphinx.ext.githubpages `](https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html) Sphinx extension seems to help automate this. – phoenix May 02 '21 at 19:58
  • You saved me a lot of trouble, I had the same issue and this fixed it. Many thanks! – masad Jun 24 '22 at 22:44
3

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.

Scott
  • 31
  • 3
  • 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. – Raf Jul 31 '20 at 15:20