Setup a GitHub repository to serve your Sphinx documentation

Prerequisites

• Python installed on your local machine

Create a Sphinx documentation

Install Sphinx on your local machine:

pip install sphinx

On GitHub, create a new repository named for example my_sphinx_repo.

Once created, clone it on your machine:

git clone https://github.com/username/my_sphinx_repo
cd ./my_sphinx_repo

Intialize in it a Sphinx documentation:

sphinx-quickstart

Enter values according to your project:

> Separate source and build directories (y/n) [n]: y
...
> Project name: your_project_name
...
> Author name(s): your_name
...
> Project release []: 0.0.1
...
> Project language [en]: en

Specifying y, we choose to store our Sphinx editable files in ./source.

We will build Sphinx in a ./docs subdirectory to suit GitHub preset setup to serve a documentation:

sphinx-build -b html ./source ./docs
# Add an empty `.nojekyll` file in `docs` repository 
# to make GitHub to not try interpret files as part of a Jekyll site
touch ./docs/.nojekyll

Publish your Sphinx documentation

Push your Sphinx documentation on GitHub:

git add .
git commit -m "First commit"
git push

In your GitHub project repo, in Settings > GitHub Pages set Source as:

• Select branch: master
• Select folder: /docs

And click Save.

Wait a bit and refresh this Settings page, when under GitHub Pagesyou will have a green notification Your Sphinx documentation will be serve at https://xxxx.github.io/my_sphinx_repo/..

Run your Sphinx documentation locally

To rebuild locally your Sphinx documentation files after modification execute:

sphinx-build -b html ./source ./docs

You can run your documentation locally starting an http server with Python:

python -m http.server 8080 --directory ./docs

It should be serve at http://localhost:8080.

Install a theme

Here we want to install the theme sphinx_rtd_theme available with a pip install:

pip install sphinx_rtd_theme

In ./source/conf.py, comment the previous theme:

#html_theme = 'alabaster'

and declare your new theme:

import sphinx_rtd_theme

html_theme = 'sphinx_rtd_theme'

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] 

Rebuild your Sphinx documentation:

sphinx-build -b html ./source ./docs

Check it with this new theme at http://localhost:8080.