Build the documentation#

The documentation is built with Sphinx using the PyData Sphinx Theme. It also includes a JupyterLite build so users can try JupyterGIS directly from the docs.

Tip

You can use conda or mamba as drop-in replacements for micromamba in the steps below, but they will not be as fast.

Prerequisites#

The docs build requires JupyterGIS to be built first:

jlpm install
jlpm build
jlpm build:packages

Create the docs environment#

Important

Ensure all other environments are deactivated first!

micromamba create -n jupytergis-docs -f docs/environment-docs.yml

Build#

From the repository root:

micromamba run -n jupytergis-docs docs/build.sh

The output will be in docs/_build/html/. Open docs/_build/html/index.html in a browser to preview.

Incremental rebuilds#

On subsequent builds, docs/clean.sh is called automatically to remove stale JupyterLite artifacts. The rest of the Sphinx build is incremental.

To do a full clean rebuild:

rm -rf docs/_build
micromamba run -n jupytergis-docs docs/build.sh

Tip

If you are making many edits, you can micromamba activate jupytergis-docs once and then just re-run docs/build.sh after each change.

Common issues#

  • build fails due to Sphinx warnings: Search the full log output for “WARNING” to find the cause.

  • examples/.ipynb_checkpoints exists: The JupyterLite build will fail. Remove it with rm -rf examples/.ipynb_checkpoints. The build script checks for this and will tell you.