Frequently Asked Questions

When I put documentation generated by Sphinx on Github pages, then it looks all mangled and broken. Why is that ?

Github pages by default uses a system called Jekyll to generate the documentation. This usually works just fine with already generated content. However Jekyll regards directory names beginning with an underscore to be special and won’t make them available on the website. Sphinx however uses directories like _source and _static for the site which means it won’t work properly. Fortunately the fix is easy. In your gh-pages branch of your project on github, simply create a file called .nojekyll in the root folder. Once you pushed that file, Jekyll will be turned off for the site and the documentation should look as intended. If you are using the Github maven plugins to deploy your site, then you can tell the site-maven-plugin to automatically maintain the .nojekyll file by adding:

<noJekyll>true</noJekyll>

to the configuration of the site-maven-plugin plugin (since version 0.5 of the plugin).