Merge branch 'trs/update-readme'

.github/workflows/ci.yaml

@@ -22,3 +22,9 @@ jobs:
     uses: ./.github/workflows/pathogen-repo-ci.yaml
     with:
       repo: nextstrain/zika-tutorial
+
+  test-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: ./devel/check-readme

README.md

@@ -25,13 +25,25 @@ Defaults for all repos.
 See also GitHub's [documentation on issue and PR templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates).
 
 
+## Actions
+
+Invoked by our GitHub Actions workflows, including the reusable workflows below.
+
+- [Setup Nextstrain CLI](actions/setup-nextstrain-cli/action.yaml)
+
+See also GitHub's [documentation on creating custom actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions).
+
+
 ## Reusable workflows
 
 Invoked by other repos.
 
 - CI for pathogen repos
   ([workflow](.github/workflows/pathogen-repo-ci.yaml))
 
+- CI for docs
+  ([workflow](.github/workflows/docs-ci.yaml))
+
 See also GitHub's [documentation on reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
 
 
@@ -45,4 +57,14 @@ Used to setup other repos.
   ([template](workflow-templates/pathogen-repo-ci.yaml),
   [properties](workflow-templates/pathogen-repo-ci.properties.json))
 
+- CI for docs
+  ([template](workflow-templates/docs-ci.yaml),
+  [properties](workflow-templates/docs-ci.properties.json))
+
 See also GitHub's [documentation on starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization).
+
+
+## Workflows for this repo itself
+
+- CI tests for the actions and reusable workflows above
+  ([workflow](.github/workflows/ci.yaml))

devel/check-readme

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Check that the README links to all files of interest; a heuristic for keeping
+# us honest about documenting the contents of this repo.
+set -euo pipefail
+
+delim=$'\x1f' # ASCII unit separator
+
+main() {
+    compare | report
+}
+
+compare() {
+    comm --output-delimiter="$delim" \
+        <(files-of-interest | sort) \
+        <(relative-links README.md | sort)
+}
+
+report() {
+    local failed=0
+
+    while IFS="$delim" read -r missing unknown found; do
+        if [[ -n $missing ]]; then
+            echo "missing link to: $missing" >&2
+            : $((failed++))
+
+        elif [[ -n $unknown ]]; then
+            echo "link to unknown file: $unknown" >&2
+            : $((failed++))
+
+        elif [[ -n $found ]]; then
+            echo "found: $found"
+        fi
+    done
+
+    return "$failed"
+}
+
+files-of-interest() {
+    git ls-files | grep -vxFf <(files-to-ignore)
+}
+
+files-to-ignore() {
+    git ls-files \
+        README.md \
+        devel/check-readme \
+        'images/*'
+}
+
+relative-links() {
+    grep -oP '\[.+?\]\(.+?\)' "$@" | grep -oP '(?<=\()(?!(https?|mailto)://).+?(?=\))'
+}
+
+main "$@"