Host your sphinx documentation.
Published in · 4 min read · Jun 13, 2021
--
Did you ever know that GitHub could host your static pages? If you didn’t, well you are not alone. GitHub provides GitHub Pages to host your documentation which contains static pages.
GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
From GitHub Pages
https://docs.github.com/en/pages
Let’s assume you already have sphinx documentation generated in a html format. If you don't know how to get started, please refer here.
By default, your GitHub pages will be disabled. Please enable them.
- Go to your GitHub repository
- Open the Settings tab and select Pages from the sidebar
- From the source section, select the branch wherever you have pushed the documentation code.
- Ideally, you could create a separate branch for your documentation say
gh-pagesor any name you see fit. - Commit the code and select the branch in the source section.
6. If you create a branch called gh-pages, GitHub will automatically recognize the documentation there and show it for you.
7. Unfortunately, you can only point to any of the root folders or the docs folder. Not any of the child folders inside them.
8. So, the index.html file should be available at the top level of the directory you are hosting. Only then your GitHub will be able to host them. Else you may get a build failure or 404 errors.
9. After saving the configuration, your page should be available at the mentioned location.
There are few pitfalls while hosting your sphinx documentation, especially on GitHub if you use the default sphinx configuration.
After hosting your documentation, if you run into 404 Page not found errors, most probably your GitHub pages is unable to find your index.html. Ensure that the index.html is available in the docs folder.
The default makefile looks like this.
The default build directory is named as _build and the built files are copied inside this folder. Since we have specified docs as the directory we have to do either of the following.
- Create a
docsfolder and copy the contents into the same (OR) - Change the default build folder as
docsin yourmakefile. If you have amake.batfile please remember to change there as well.
I would prefer the second option. Let’s change the build folder in the makefile and rebuild again.
$make htmlNow the docs folder, will have the below contents.
--docs
|--doctrees
|--html
|--index.html
|..However, the index.html is still not inside the top level of docs folder. So we may have to add another index.html and write a redirection code to redirect to the index.html inside the HTML folder.
<meta http-equiv="refresh" content="0; url=./html/index.html" />This should resolve the 404 errors.
https://github.com/sphinx-doc/sphinx/issues/3382
Sometimes, after hosting the documentation the selected theme may not be displayed properly. This could be because the default build folders are named with learning underscores [_build, _static].
That’s because GitHub by default publishes the pages through jekyll. We need to add an empty .nojekyll file in the docs directory or the root directory.
Now the page looks like below,
All the above mentioned code is available in the below repository
https://github.com/dineshkumarkb/sphinx-doc
The hosted document is available at
