This repository is meant to write and manage the official documentation of MapX (source code), an online platform for managing geospatial data on natural resources, developed by GRID-Geneva - a data centre resulting from the partnership between UN Environment Programme, the Swiss Federal Office for the Environment and the University of Geneva.

Building the documentation

The documentation uses the dedicated Docker image, based on sphinx-latexpdf to support both HTML and PDF output. Dockerfile.sphinx9 installs Sphinx 9.2.0, Docutils 0.21.2, and pinned versions of the required extensions and theme.

Use the image name git.unepgrid.ch/mapx/sphinx-latexpdf-mapx:9.2.0-2. The tag identifies the Sphinx version (9.2.0) and the MapX image revision (2). Increment the revision when changing the image or its dependencies without changing the Sphinx version. Revision 2 adds sphinxcontrib-video==0.4.2 for embedded videos.

Build the image locally before using a new tag:

docker build \
      -f Dockerfile.sphinx9 \
      -t git.unepgrid.ch/mapx/sphinx-latexpdf-mapx:9.2.0-2 .

Build PDF & HTML:

# The PDF document is copied to `_static` to allow PDF export from the HTML

docker run --rm \
      --volume "$(pwd):/docs" \
      git.unepgrid.ch/mapx/sphinx-latexpdf-mapx:9.2.0-2 sh -c \
      "rm -rf _build/ &&
       make latexpdf &&
       cp _build/latex/mapx.pdf _static/ &&
       make html"

To publish the builder image for both Intel/AMD and ARM machines:

docker buildx build \
      --platform linux/amd64,linux/arm64 \
      -f Dockerfile.sphinx9 \
      -t git.unepgrid.ch/mapx/sphinx-latexpdf-mapx:9.2.0-2 \
      --push .

Embedding videos

The builder image includes sphinxcontrib-video, enabled as sphinxcontrib.video in conf.py. Rebuild the image when upgrading from an older revision that does not include the extension.

Save an MP4 recording and a PNG screenshot alongside the relevant documentation. Paths in the example below are relative to the .rst file. Replace them with your own files:

.. only:: html

   .. video:: ./media/filter-views.mp4
      :width: 100%
      :preload: metadata
      :playsinline:
      :alt: Demonstration of filtering views in MapX.
      :caption: Filtering views in MapX.

.. only:: latex

   .. figure:: ./img/filter-views.png
      :width: 12cm
      :align: center
      :alt: The view filtering controls in MapX.

      Filtering views in MapX.

Playback controls are enabled by default. The video is copied into the HTML output automatically. Videos are not rendered in the PDF, so keep the only:: html block and provide a screenshot with only:: latex. The screenshot must be supplied separately; the extension does not extract it from the video. Keep written instructions available for both outputs.

Prepare and optimize recordings before building the documentation, for example with FFmpeg on your computer. FFmpeg is not required in the builder image. The scale filter keeps both dimensions even, as required by H.264 with yuv420p.

for file in *.mov; do
  [ -f "$file" ] || continue

  ffmpeg -i "$file" \
    -vf "fps=20,scale=w='trunc(min(1280,iw)/2)*2':h=-2" \
    -c:v libx264 \
    -preset slow \
    -crf 22 \
    -pix_fmt yuv420p \
    -movflags +faststart \
    -an \
    "${file%.mov}.mp4"
done

Disclaimer

Although, the content has been prepared and reviewed with utmost care by the authors, errors may still exist. As such, GRID-Geneva and the authors disclaim any responsibility or liability for errors and their potential impact.

We welcome any feedback regarding inaccuracies you may encounter and encourage you to contact us at info@mapx.org.