Using Docker

If you want to use Docker, you can skip the remaining sections.

To build the html files (equivalent to Method #1 below):

> docker run -t --rm -v "$(pwd)":/web -u $(id -u):$(id -g) dldl/sphinx-server make html

To autobuild the html files when changes are detected (equivalent to Method #2 below):

> docker run -it --rm -v "$(pwd)/source":/web -u $(id -u):$(id -g) -p 8000:8000 --name sphinx-server dldl/sphinx-server

Setup

If not already installed, then install pipenv. Details here: https://pypi.org/project/pipenv/

> pip install pipenv

or

> brew install pipenv

Install all dependencies for the project

> pipenv install --dev

To build documentation

First, start a shell in the project's environment

> pipenv shell

Method 1

Generate html files in the 'build' directory. Repeat this manually after changing files under the 'source' directory.

> make html

Now open a browser to the build/html/index.html file.

Method 2

More conveniently, start an autobuild service that will automatically update build/html files if a file under 'source' changes.

> make livehtml

Open a browser to http://127.0.0.1:8000/ to see changes. Hit Ctrl-C to stop the autobuild service.

Note that sometimes you want it to rebuild everything so that the sidebar and other global elements are updated. To do a complete refresh, just stop the autobuild service (if it is running), delete the build directory, and rebuild the documentation.