How to create a static website with sphinx-docs

Sphinx-docs is really popular in project documentation, I myself wanted to give a try also to write my own notes. Because I would like to publish the site using github pages. I started checking out my own repository from git. I assume you have installed python3 and pip.

  1. Install sphinx

$ pip install -U sphinx

  1. Run sphinx-quickstart from the directory where pages will be generated.

$ sphinx-quickstart
> Separate source and build directories (y/n) [n]: y

  1. Rename source directory to docs. Directory tree should look like:

|-- site
    |-- build
    |-- docs

  1. Change source directory in Makefile

SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = docs
BUILDDIR      = build

  1. You can already generate pages by running:

$ make html
Running Sphinx v5.3.0
...
The HTML pages are in build/html.

  1. If you like try to some of the sphinx themes

pip install yummy-sphinx-theme

Edit the docs/conf.py as:

# -- Options for HTML output -------------------------------------------------
html_theme = 'yummy_sphinx_theme'