Module system deep dive tutorial (#645)

* Draft module system introduction tutorial

* add intro/conclusion, rework prose, follow styleguide, clean diffs

* Review pass

* Apply suggestions from code review

* fix whitespace

* add some more motivation the each section

* make scripts downloadable

* address review comments

* make script actually work

...hopefully. can't test it without Google API key

* add file watching

yes, this looks scary, and yes, it works.

* update diff and wording

* more notes on potential pitfalls

* be explicit which `map` we mean

* split nullable from default values

* also wrap the geocode script

* work through the tutorial to the end

* add tutorial overview

* `lib` is always passed

* add separate section for `evalModules` and fix link

* make option strucutre more self-explanatory

* explain command line invocations

* add note on incomplete reference documentation

* add more highlight to the `config` distinction

* fix parameter passing to the `./map` script

* fix typo

* fix wording

* link to summer of nix

* add missing word

* link to Google Maps API docs

* more explicit requirement

* use correct module system terminology

* Update source/tutorials/module-system/module-system.md

* Apply suggestions from code review

* whitespace

* module-system.md: replace comments with captions

* add missing lang for code-block

* Update module system title

* change most headers to be about module features (#797)

* change most headers to be about module features

Some headers could not be made about module features, and that's a
strong signal that those sections should be removed.

* Apply suggestions from code review

* module-system.md: Fix header casing

Co-authored-by: Alexander Groleau <source@proof.construction>
Co-authored-by: asymmetric <lorenzo@mailbox.org>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

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
 Packaging existing software <packaging-existing-software.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