Setup a GitHub repository to serve your Sphinx documentation

Featured image

Sphinx and GitHub provide an efficient and free way to publish your documentation online. Here we describe how to do so.


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
cd ./my_sphinx_repo

Intialize in it a Sphinx documentation:


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

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/, 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.

See also

Monitor SSIS job and package executions

date_range 02/09/2020

Featured image

How to monitor SSIS job and package executions.

Enable network connectivity between Docker containers on CentOS 8

date_range 15/08/2020

Featured image

Enable a network connectivity between Docker containers on CentOS 8.

Install Anaconda Python Distribution for all users on RHEL/CentOS 7

date_range 10/04/2019

Featured image

The easiest way to install Python and Jupyter Notebook is probably with Anaconda.

Anaconda is a free and open source distribution of the Python programming language for data science and machine learning related applications, that aims to simplify package management and deployment. Package versions are managed by the package management system conda.