remove pandoc dependency from main game (#2084)

Closes #2083

Rendering a matrix of command attributes was originally implemented in #1658.  But this generated the data to drive the table at runtime, which pulled in an unfortunate Pandoc dependency.

To work around this, let's just pre-generate the data offline.

# Demo

1. `scripts/play.sh`
2. Visit http://localhost:5357/command-matrix.html

app/doc/Main.hs

@@ -19,6 +19,7 @@ cliParser =
       , command "editors" (info (EditorKeywords <$> editor <**> helper) $ progDesc "Output editor keywords")
       , command "keys" (info (pure SpecialKeyNames) $ progDesc "Output list of recognized special key names")
       , command "cheatsheet" (info (CheatSheet <$> address <*> cheatsheet <**> helper) $ progDesc "Output nice Wiki tables")
+      , command "commands" (info (pure CommandsData <**> helper) $ progDesc "Output JSON data for commands matrix")
       , command "pedagogy" (info (pure TutorialCoverage) $ progDesc "Output tutorial coverage")
       ]
  where

scripts/gen/commands-matrix-data.sh

@@ -0,0 +1,6 @@
+#!/bin/bash -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+cd $SCRIPT_DIR/../..
+
+cabal run -j -O0 -- swarm-docs commands | jq . > web/data/commands.json

src/swarm-doc/Swarm/Doc/Gen.hs

@@ -24,6 +24,7 @@ module Swarm.Doc.Gen (
 
 import Control.Lens (view, (^.))
 import Control.Monad (zipWithM, zipWithM_)
+import Data.Aeson.Text (encodeToLazyText)
 import Data.Containers.ListUtils (nubOrd)
 import Data.Foldable (toList)
 import Data.List qualified as List
@@ -36,7 +37,9 @@ import Data.Set qualified as Set
 import Data.Text (Text, unpack)
 import Data.Text qualified as T
 import Data.Text.IO qualified as T
+import Data.Text.Lazy.IO qualified as TL
 import Data.Tuple (swap)
+import Swarm.Doc.Command (getCatalog)
 import Swarm.Doc.Keyword
 import Swarm.Doc.Pedagogy
 import Swarm.Doc.Util
@@ -73,6 +76,8 @@ data GenerateDocs where
   SpecialKeyNames :: GenerateDocs
   -- | Cheat sheets for inclusion on the Swarm wiki.
   CheatSheet :: PageAddress -> SheetType -> GenerateDocs
+  -- | JSON representation of commands metadata matrix
+  CommandsData :: GenerateDocs
   -- | List command introductions by tutorial
   TutorialCoverage :: GenerateDocs
   deriving (Eq, Show)
@@ -94,6 +99,7 @@ generateDocs = \case
         mapM_ editorGen enumerate
   SpecialKeyNames -> generateSpecialKeyNames
   CheatSheet address s -> makeWikiPage address s
+  CommandsData -> TL.putStrLn $ encodeToLazyText getCatalog
   TutorialCoverage -> renderTutorialProgression >>= putStrLn . T.unpack
 
 -- ----------------------------------------------------------------------------

src/swarm-web/Swarm/Web.hs

@@ -63,7 +63,6 @@ import Servant
 import Servant.Docs (ToCapture)
 import Servant.Docs qualified as SD
 import Servant.Docs.Internal qualified as SD (renderCurlBasePath)
-import Swarm.Doc.Command
 import Swarm.Game.Entity (EntityName, entityName)
 import Swarm.Game.Robot
 import Swarm.Game.Scenario.Objective
@@ -110,7 +109,6 @@ type SwarmAPI =
     :<|> "code" :> "render" :> ReqBody '[PlainText] T.Text :> Post '[PlainText] T.Text
     :<|> "code" :> "run" :> ReqBody '[PlainText] T.Text :> Post '[PlainText] T.Text
     :<|> "paths" :> "log" :> Get '[JSON] (RingBuffer CacheLogEntry)
-    :<|> "commands" :> Get '[JSON] CommandCatalog
     :<|> "repl" :> "history" :> "full" :> Get '[JSON] [REPLHistItem]
     :<|> "map" :> Capture "size" AreaDimensions :> Get '[JSON] GridResponse
 
@@ -166,7 +164,6 @@ mkApp state events =
     :<|> codeRenderHandler
     :<|> codeRunHandler events
     :<|> pathsLogHandler state
-    :<|> cmdMatrixHandler state
     :<|> replHistHandler state
     :<|> mapViewHandler state
 
@@ -246,9 +243,6 @@ pathsLogHandler appStateRef = do
   appState <- liftIO (readIORef appStateRef)
   pure $ appState ^. gameState . pathCaching . pathCachingLog
 
-cmdMatrixHandler :: ReadableIORef AppState -> Handler CommandCatalog
-cmdMatrixHandler _ = pure getCatalog
-
 replHistHandler :: ReadableIORef AppState -> Handler [REPLHistItem]
 replHistHandler appStateRef = do
   appState <- liftIO (readIORef appStateRef)

swarm.cabal

@@ -499,7 +499,6 @@ library swarm-web
     witch,
 
   build-depends:
-    swarm:swarm-doc,
     swarm:swarm-engine,
     swarm:swarm-lang,
     swarm:swarm-scenario,

web/data/README.md

@@ -0,0 +1,4 @@
+Regenerate this data with:
+```
+scripts/gen/commands-matrix-data.sh
+```

web/index.html

@@ -7,5 +7,6 @@
     <h1>Hello Swarm player!</h1>
     <p>Looking for the <a href="api">Web API docs</a>?</p>
     <p>Or an <a href="play.html">experimental web frontend</a> for the game?</p>
+    <p>Or the <a href="command-matrix.html">Command attributes matrix?</p>
   </body>
 </html>

web/script/command-matrix.js

@@ -42,7 +42,7 @@ function insertTableRows(myTableBody, entries) {
 }
 
 function doFetch(myTable) {
-    fetch("commands")
+    fetch("data/commands.json")
     .then((response) => {
     if (!response.ok) {
         throw new Error(`HTTP error, status = ${response.status}`);