Autogenerate cryptol-remote-api docs (and check them in CI)

Unfortunately, the autogenerated documentation (now located in `Cryptol.rst`)
doesn't yet have all of the information contained within the hand-written
documentation (now located in `old-Cryptol.rst`—see #1206. In pursuit of
eventually fixing that issue, the CI now makes sure that any changes to the
autogenerated documentation are checked in.

.github/ci.sh

@@ -147,6 +147,10 @@ test_rpc() {
   ./cry rpc-test
 }
 
+check_rpc_docs() {
+  ./cry rpc-docs
+}
+
 bundle_files() {
   doc=dist/share/doc/cryptol
   lib=dist/share/cryptol

.github/workflows/ci.yml

@@ -129,6 +129,9 @@ jobs:
       - shell: bash
         run: .github/ci.sh test_rpc
         if: runner.os != 'Windows'
+      - shell: bash
+        run: .github/ci.sh check_rpc_docs
+        if: runner.os != 'Windows'
 
       - if: matrix.ghc == '8.8.4'
         uses: actions/upload-artifact@v2

cry

@@ -21,6 +21,7 @@ Available commands:
   test                         Run some tests (may take a while)
   quick-test                   Like "test" but run fewer tests by default
   rpc-test                     Run RPC server tests
+  rpc-docs                     Check that the RPC documentation is up-to-date
   exe-path                     Print the location of the local executable
 EOM
 }
@@ -90,6 +91,12 @@ case $COMMAND in
     $DIR/cryptol-remote-api/run_rpc_tests.sh
     ;;
 
+  rpc-docs)
+    echo "Checking cryptol-remote-api docs (Cryptol.rst) are up-to-date with server"
+    DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+    $DIR/cryptol-remote-api/check_docs.sh
+    ;;
+
 
   help) show_usage && exit 0 ;;
 

cryptol-remote-api/check_docs.sh

@@ -0,0 +1,14 @@
+#! /bin/bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+cd $DIR/docs
+
+export CRYPTOL_SERVER=$(cabal v2-exec which cryptol-remote-api)
+if [[ ! -x "$CRYPTOL_SERVER" ]]; then
+  echo "could not locate cryptol-remote-api executable - try executing with cabal v2-exec"
+  exit 1
+fi
+
+$CRYPTOL_SERVER doc > TEMP.rst
+diff Cryptol.rst TEMP.rst

cryptol-remote-api/docs/.gitignore

@@ -1 +1,2 @@
 _build/
+TEMP.rst