Add a script to check documentation for ToC entries. (#8356)

This script verifies that each document in the docs and architecture directory
has a corresponding table-of-contents entry in its README file.  It can be run
manually from the command line.

- Hook up this script to run in CI (optional workflow).
- Update ADR ToC to include missing entries this script found.

.github/workflows/docs-toc.yml

@@ -0,0 +1,20 @@
+# Verify that important design docs have ToC entries.
+name: Check documentation ToC
+on:
+  pull_request:
+    push:
+      branches:
+        - master
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: technote-space/get-diff-action@v6.0.1
+        with:
+          PATTERNS: |
+            docs/architecture/**
+            docs/rfc/**
+      - run: ./docs/presubmit.sh
+        if: env.GIT_DIFF

docs/architecture/README.md

@@ -104,12 +104,17 @@ None
 - [ADR-013: Symmetric-Crypto](./adr-013-symmetric-crypto.md)
 - [ADR-022: ABCI-Errors](./adr-022-abci-errors.md)
 - [ADR-030: Consensus-Refactor](./adr-030-consensus-refactor.md)
+- [ADR-036: Empty Blocks via ABCI](./adr-036-empty-blocks-abci.md)
 - [ADR-037: Deliver-Block](./adr-037-deliver-block.md)
 - [ADR-038: Non-Zero-Start-Height](./adr-038-non-zero-start-height.md)
+- [ADR-040: Blockchain Reactor Refactor](./adr-040-blockchain-reactor-refactor.md)
 - [ADR-041: Proposer-Selection-via-ABCI](./adr-041-proposer-selection-via-abci.md)
+- [ADR-042: State Sync Design](./adr-042-state-sync.md)
 - [ADR-045: ABCI-Evidence](./adr-045-abci-evidence.md)
+- [ADR-050: Improved Trusted Peering](./adr-050-improved-trusted-peering.md)
 - [ADR-057: RPC](./adr-057-RPC.md)
+- [ADR-064: Batch Verification](./adr-064-batch-verification.md)
 - [ADR-069: Node Initialization](./adr-069-flexible-node-initialization.md)
-- [ADR-071: Proposer-Based Timestamps](adr-071-proposer-based-timestamps.md)
+- [ADR-071: Proposer-Based Timestamps](./adr-071-proposer-based-timestamps.md)
+- [ADR-073: Adopt LibP2P](./adr-073-libp2p.md)
 - [ADR-074: Migrate Timeout Parameters to Consensus Parameters](./adr-074-timeout-params.md)
-

docs/presubmit.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# This script verifies that each document in the docs and architecture
+# directory has a corresponding table-of-contents entry in its README file.
+#
+# This can be run manually from the command line.
+# It is also run in CI via the docs-toc.yml workflow.
+#
+set -euo pipefail
+
+readonly base="$(dirname $0)"
+cd "$base"
+
+readonly workdir="$(mktemp -d)"
+trap "rm -fr -- '$workdir'" EXIT
+
+checktoc() {
+    local dir="$1"
+    local tag="$2"'-*-*'
+    local out="$workdir/${dir}.out.txt"
+    (
+        cd "$dir" >/dev/null
+        find . -type f -maxdepth 1 -name "$tag" -not -exec grep -q "({})" README.md ';' -print
+    ) > "$out"
+    if [[ -s "$out" ]] ; then
+        echo "-- The following files in $dir lack a ToC entry:
+"
+        cat "$out"
+        return 1
+    fi
+}
+
+err=0
+
+# Verify that each RFC and ADR has a ToC entry in its README file.
+checktoc architecture adr || ((err++))
+checktoc rfc rfc || ((err++))
+
+exit $err