CODEWITHSUNDEEP
pythondjangogithub-pagespython-sphinx
Abdul Rehman
Abdul Rehman

Reputation: 5664

Python Sphinx css not working on github pages

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?

Upvotes: 14

Views: 4082

Answers (5)

Shashanka Prajapati
Shashanka Prajapati

Reputation: 391

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",
]

...

Upvotes: 1

m8mble
m8mble

Reputation: 1545

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

Upvotes: 6

Eric Wiener
Eric Wiener

Reputation: 5957

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: Google Console showing error messages

Upvotes: 0

Peter Curran
Peter Curran

Reputation: 382

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.

Upvotes: 16

bertty contreras
bertty contreras

Reputation: 1

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.

Upvotes: 0

Related Questions