23

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.

Improve this question
3
  • Does this answer your question? Using github actions to publish documentation Commented Jun 28, 2020 at 19:15
  • Unfortunately not. Thanks anyway. Commented Jul 31, 2020 at 8:00
  • 1
    In case it helps, I found a different solution that I posted here Commented Jan 5, 2021 at 14:48

2 Answers 2

Reset to default
21

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)

Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

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.
The sphinx.ext.githubpages Sphinx extension seems to help automate this.
You saved me a lot of trouble, I had the same issue and this fixed it. Many thanks!
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.

Improve this answer

1 Comment

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.