Module system deep dive tutorial

source/conf.py

@@ -178,7 +178,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static', 'tutorials/module-system/files']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

source/tutorials/index.md

@@ -12,4 +12,5 @@ nix-language.md
 learning-journey/index.md
 nixos/index.md
 cross-compilation.md
+module-system/module-system.md
 ```

source/tutorials/module-system/files/geocode

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cachedir=~/.cache/google-api/geocode
+mkdir -p "$cachedir"
+hash=$(echo "$1" | sha256sum - | cut -d' ' -f1)
+cachefile="$cachedir/$hash"
+
+if [[ ! -f "$cachefile" ]]; then
+
+  keyFile=${XDG_DATA_HOME:-~/.local/share}/google-api/key
+
+  if [[ ! -f "$keyFile" ]]; then
+    mkdir -p "$(basename "$keyFile")"
+    echo "No Google API key found in $keyFile" >&2
+    echo "For getting one, see https://developers.google.com/maps/documentation/geocoding/overview#before-you-begin" >&2
+    exit 1
+  fi
+
+  key=$(cat "$keyFile")
+
+
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' exit
+
+  output=$tmp/output
+
+  curlArgs=(
+    https://maps.googleapis.com/maps/api/geocode/json
+    --silent --show-error --get --output "$output" --write-out '%{http_code}'
+    --data-urlencode address="$1"
+  )
+
+  #echo curl ''${curlArgs[@]@Q} >&2
+
+  curlArgs+=(--data-urlencode key="$key")
+
+  if status=$(curl "${curlArgs[@]}"); then
+    if [[ "$status" == 200 ]]; then
+      jq -r '.results[0].geometry.location as $loc | "\($loc | .lat),\($loc | .lng)"' "$output" > "$cachefile"
+    else
+      echo "API returned non-200 HTTP status code $status, output is" >&2
+      cat "$output" >&2
+      exit 1
+    fi
+  else
+    code=$?
+    echo "curl exited with code $code" >&2
+    exit 1
+  fi
+fi
+
+cat "$cachefile"

source/tutorials/module-system/files/map

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cachedir=${XDG_CACHE_HOME:-~/.cache}/google-api/maps-static
+mkdir -p "$cachedir"
+hash=$(echo "$@" | sha256sum - | cut -d' ' -f1)
+cachefile="$cachedir/$hash"
+
+if [[ ! -f "$cachefile" ]]; then
+
+  keyFile=${XDG_DATA_HOME:-~/.local/share}/google-api/key
+
+  if [[ ! -f "$keyFile" ]]; then
+    mkdir -p "$(basename "$keyFile")"
+    echo "No Google API key found in $keyFile" >&2
+    echo "For getting one, see https://developers.google.com/maps/documentation/maps-static/start#before-you-begin" >&2
+    exit 1
+  fi
+
+  key=$(cat "$keyFile")
+
+
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' exit
+
+  output=$tmp/output
+
+  curlArgs=(
+    https://maps.googleapis.com/maps/api/staticmap
+    --silent --show-error --get --output "$output" --write-out %{http_code}
+  )
+
+  for arg in "$@"; do
+    curlArgs+=(--data-urlencode "$arg")
+  done
+
+  #echo curl ''${curlArgs[@]@Q} >&2
+
+  curlArgs+=(--data-urlencode key="$key")
+
+  if status=$(curl "${curlArgs[@]}"); then
+    if [[ "$status" == 200 ]]; then
+      mv "$output" "$cachefile"
+    else
+      echo "API returned non-200 HTTP status code $status, output is" >&2
+      cat "$output" >&2
+      exit 1
+    fi
+  else
+    code=$?
+    echo "curl exited with code $code" >&2
+    exit 1
+  fi
+fi
+
+if [[ -t 1 ]]; then
+  echo "Successful, but won't output image to tty, pipe to a file or icat instead" >&2
+else
+  cat "$cachefile"
+fi