Python Sphinx css not working on github pages

Question

I have created documentation for a Django project using Sphinx and copy the content of html folder after executing the make html command into the docs/ folder of my repo and push it to Github. After that I have set this docs/ directory to Github Pages, now it's loading the documentation but the css is not working it's just a docs text with any styling.

Here's my Sphinx's config.py:

import os
import sys
import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'PROJECT_NAME.settings'
django.setup()

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'bizstyle'
html_static_path = ['_static']
BUILDDIR = '.'

and here's the link to the docs page from GitHub pages: https://arycloud.github.io/Tagging-Project-for-Machine-Learning-Natural-Language-Processing/

what can be wrong?

Janenejanenna

None of the CSS or JavaScript loads. For how to fix it, you can post-process the HTML. – Inurn

Answer 1

I've used sphinx/githubpages to document one of my python projects. I found this blog post very helpful. Here's an example of my working docs directory.

Adding a .nojekyll file in the docs directory will fix the issue. This tells github pages not to publish the files through jekyll. With this, you won't need to change any directory names and it should work with "_" prefixes.

Marginalia

Answer 2

TL;DR

Add a .nojekyll file to the toplevel directory of your repository (source).

In contrast to previous answers, the .nojekyll file has to be on the toplevel - even if you serve your page from docs/.

Background:

Github pages uses jekyll by default. When jekyll generates a site, files whose name starts with an underscore are not included in the destination (source, bottom). This is why they are not served by github pages as long as you are lacking a .nojekyll (to disable jekyll processing).

Supinator

Worked for me, but I added .nojekyll file to docs/ and my github pages build was staring in docs/ – Louden

Answer 3

There is a sphinx extension for github pages: sphinx.ext.githubpages

Appending this to the list of extensions in the Sphinx's config file docs/conf.py should do the trick.

...

extensions = [
    ...,
    "sphinx.ext.githubpages",
]

...

Globigerina

Answer 4

I was doing the same thing; the issue is with the underscore in the folder name. The underscore means to ignore the folder.

I used sed to modify it.

Incorruption

Answer 5

For me the issue was I used the Read the Docs theme and added it as the HTML theme:

html_theme = "sphinx_rtd_theme"

but I forgot to include it in the extensions:

extensions = [
    ...
    "sphinx_rtd_theme",
]

and import it:

import sphinx_rtd_theme

I was able to figure this out by looking at the console error messages and seeing what the issue was:

Execration