Using Sphinx and GitHub Pages for your Python project homepage

First, create a sphinx directory and run sphinx-quickstart in it to get a template of doc scripts. Inside sphinx:

1. conf.py:
   • You might want to comment out the sys.path customization in the beginning of the file to add in your module
   • sphinx.ext.autodoc is a good extension to be added to extensions. This will include documentation from docstrings in your Python code
   • If you get warning about static folders, you should remove it from html_static_path if not using it
2. index.rst: you can use automodule etc. from autodoc to add new content to index page
3. Copy over generated files in $BUILDDIR/html to docs directory in repo root

Second, create docs/.nojekyll to prevent GitHub to eat your static files under _static. (Reason: in Jekyll, underscore-something means jekyll files to be ignored).

Finally, in Github project setting, you are recommended to publish in master/docs. This can help you save a lot of hassles (of changing branches).

Related:

https://daler.github.io/sphinxdoc-test/includeme.html