docs

src/Swarm/Docs/Pedagogy.hs

@@ -4,6 +4,11 @@
 -- SPDX-License-Identifier: BSD-3-Clause
 --
 -- Assess pedagogical soundness of the tutorials.
+--
+-- Approach:
+-- 1. Obtain a list of all of the tutorial scenarios, in order
+-- 2. Search their "solution" code for `commands`
+-- 3. "fold" over the tutorial list, noting which tutorial was first to introduce each command
 module Swarm.Docs.Pedagogy (
   renderTutorialProgression,
   generateIntroductionsSequence,
@@ -22,11 +27,11 @@ import Data.Map qualified as M
 import Data.Maybe (mapMaybe)
 import Data.Set (Set)
 import Data.Set qualified as S
-import Data.Text qualified as T
 import Data.Text (Text)
+import Data.Text qualified as T
 import Swarm.Docs.Util
 import Swarm.Game.Entity (loadEntities)
-import Swarm.Game.Scenario (Scenario, scenarioDescription, scenarioObjectives, scenarioSolution, scenarioName)
+import Swarm.Game.Scenario (Scenario, scenarioDescription, scenarioName, scenarioObjectives, scenarioSolution)
 import Swarm.Game.Scenario.Objective (objectiveGoal)
 import Swarm.Game.ScenarioInfo (ScenarioCollection, ScenarioInfoPair, flatten, loadScenariosWithWarnings, scenarioCollectionToList, scenarioPath)
 import Swarm.Language.Module (Module (..))
@@ -97,7 +102,7 @@ getDescCommands s =
 
 -- | Extract the command names from the source code of the solution.
 --
--- NOTE: The processed solution stored in the scenario has been "decorated" in a sense;
+-- NOTE: The processed solution stored in the scenario has been "elaborated";
 -- e.g. `noop` gets inserted for an empty `build {}` command.
 -- So we explicitly ignore `noop`.
 --
@@ -156,27 +161,30 @@ loadScenarioCollection = simpleErrorHandle $ do
 renderUsagesMarkdown :: Int -> CoverageInfo -> Text
 renderUsagesMarkdown idx (CoverageInfo (TutorialInfo (s, si) _sCmds dCmds) novelCmds) =
   T.unlines $
-    "" :
-    firstLine
+    ""
+      : firstLine
       : "================"
       : otherLines
  where
-  otherLines = concat
-    [ pure $ "`" <> T.pack (view scenarioPath si) <> "`"
-    , [""]
-    , pure $ "*" <> T.strip (view scenarioDescription s) <> "*"
-    , [""]
-    , renderSection "Commands introduced in this solution" $ renderCmds novelCmds
-    , [""]
-    , renderSection "Commands found in description" $ renderCmds dCmds
-    ]
+  otherLines =
+    concat
+      [ pure $ "`" <> T.pack (view scenarioPath si) <> "`"
+      , [""]
+      , pure $ "*" <> T.strip (view scenarioDescription s) <> "*"
+      , [""]
+      , renderSection "Commands introduced in this solution" $ renderCmds novelCmds
+      , [""]
+      , renderSection "Commands found in description" $ renderCmds dCmds
+      ]
 
   renderSection title content =
     [title, "----------------"] <> content
 
-  renderCmds cmds = pure $ if null cmds
-    then "<none>"
-    else commaList . map linkifyCommand . sort . map (T.pack . show) . S.toList $ cmds
+  renderCmds cmds =
+    pure $
+      if null cmds
+        then "<none>"
+        else commaList . map linkifyCommand . sort . map (T.pack . show) . S.toList $ cmds
 
   linkifyCommand c = "[" <> c <> "](" <> commandsWikiPrefix <> c <> ")"