github pages based on sphinx - sample documentation:
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
_build different sphinx ascii art Dec 9, 2017
_static init Dec 5, 2017
.gitignore _build diretory must be in commit stage, otherwise changes can't be s… Dec 9, 2017
.nojekyll bypassing jekyll Dec 5, 2017
Makefile init Dec 5, 2017 config changed Dec 9, 2017
index.rst a sphinx Dec 9, 2017
pages-created-from-gh-pages-branch.png debug echo dropped Dec 9, 2017
sphinx-pages.rst index in toctree Dec 9, 2017


github pages based on sphinx

With calling the sphinx-2-gh-pages-converter shell script you can publish your sphinx based documentation to github pages. The documentation will be available following this pattern:


(e.g. enables pages automatically if a gh-pages branch exists: gh-pages recognition


  • git repository exists in current directory
  • sphinx files are part of master branch
  • git remote is defined
  • permissions to pull, push are granted to the user executing the script
  • os package manager is apt-get
  • python, pip is installed

Project notes

apt-get install python-sphinx #sudo apt-get install python-sphinx
pip install sphinx_rtd_theme #sudo -H pip install sphinx_rtd_theme
pip install sphinx-autobuild #sudo -H pip install sphinx-autobuild
Project setup
sphinx-quickstart # followed all default but set names and author
# edits as described in
# a sample index.rst file
# .gitignore from
# generate docs locally
sphinx-build -b html . _build
sphinx-autobuild . _build --open-browser # opens built docs in browser

Blog Post