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
:
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 toextensions
. This will include documentation from docstrings in your Python code- If you get warning about
static
folders, you should remove it fromhtml_static_path
if not using it
- You might want to comment out the
index.rst
: you can useautomodule
etc. from autodoc to add new content to index page- Copy over generated files in
$BUILDDIR/html
todocs
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