extract doc generator to separate executable (#1671)

Closes #1443.

Also added `-Wunused-packages` to clean up dependencies.

## Demo

This still works as usual:

    stack run

Output editor keywords:

    stack run swarm-docs -- editors --emacs

Author: kostmo

app/Main.hs

@@ -7,16 +7,13 @@
 module Main where
 
 import Data.Foldable qualified
-import Data.Maybe (fromMaybe)
 import Data.Text (Text, pack)
-import Data.Text qualified as T
 import Data.Text.IO qualified as Text
 import GitHash (GitInfo, giBranch, giHash, tGitInfoCwdTry)
 import Options.Applicative
 import Prettyprinter
 import Prettyprinter.Render.Text qualified as RT
 import Swarm.App (appMain)
-import Swarm.Doc.Gen (EditorType (..), GenerateDocs (..), PageAddress (..), SheetType (..), generateDocs)
 import Swarm.Game.Scenario.Topography.Area (AreaDimensions (..))
 import Swarm.Game.World.Render (OuputFormat (..), RenderOpts (..), doRenderCmd)
 import Swarm.Language.LSP (lspMain)
@@ -45,7 +42,6 @@ type Width = Int
 data CLI
   = Run AppOpts
   | Format Input (Maybe Width)
-  | DocGen GenerateDocs
   | RenderMap FilePath RenderOpts
   | LSP
   | Version
@@ -55,7 +51,6 @@ cliParser =
   subparser
     ( mconcat
         [ command "format" (info (Format <$> format <*> optional widthOpt <**> helper) (progDesc "Format a file"))
-        , command "generate" (info (DocGen <$> docgen <**> helper) (progDesc "Generate docs"))
         , command "map" (info (render <**> helper) (progDesc "Render a scenario world map."))
         , command "lsp" (info (pure LSP) (progDesc "Start the LSP"))
         , command "version" (info (pure Version) (progDesc "Get current and upstream version."))
@@ -97,46 +92,6 @@ cliParser =
   widthOpt :: Parser Width
   widthOpt = option auto (long "width" <> metavar "COLUMNS" <> help "Use layout with maximum width")
 
-  docgen :: Parser GenerateDocs
-  docgen =
-    subparser . mconcat $
-      [ command "recipes" (info (pure RecipeGraph) $ progDesc "Output graphviz dotfile of entity dependencies based on recipes")
-      , 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 "pedagogy" (info (pure TutorialCoverage) $ progDesc "Output tutorial coverage")
-      , command "endpoints" (info (pure WebAPIEndpoints) $ progDesc "Generate markdown Web API documentation.")
-      ]
-
-  editor :: Parser (Maybe EditorType)
-  editor =
-    Data.Foldable.asum
-      [ pure Nothing
-      , Just VSCode <$ switch (long "code" <> help "Generate for the VS Code editor")
-      , Just Emacs <$ switch (long "emacs" <> help "Generate for the Emacs editor")
-      ]
-  address :: Parser PageAddress
-  address =
-    let replace a b = T.unpack . T.replace a b . T.pack
-        opt n =
-          fmap (fromMaybe "") . optional $
-            option
-              str
-              ( long n
-                  <> metavar "ADDRESS"
-                  <> help ("Set the address of " <> replace "-" " " n <> ". Default no link.")
-              )
-     in PageAddress <$> opt "entities-page" <*> opt "commands-page" <*> opt "capabilities-page" <*> opt "recipes-page"
-  cheatsheet :: Parser (Maybe SheetType)
-  cheatsheet =
-    Data.Foldable.asum
-      [ pure Nothing
-      , Just Entities <$ switch (long "entities" <> help "Generate entities page (uses data from entities.yaml)")
-      , Just Recipes <$ switch (long "recipes" <> help "Generate recipes page (uses data from recipes.yaml)")
-      , Just Capabilities <$ switch (long "capabilities" <> help "Generate capabilities page (uses entity map)")
-      , Just Commands <$ switch (long "commands" <> help "Generate commands page (uses constInfo, constCaps and inferConst)")
-      , Just Scenario <$ switch (long "scenario" <> help "Generate scenario schema page")
-      ]
   seed :: Parser (Maybe Int)
   seed = optional $ option auto (long "seed" <> short 's' <> metavar "INT" <> help "Seed to use for world generation")
   webPort :: Parser (Maybe Int)
@@ -218,7 +173,6 @@ main = do
   cli <- execParser cliInfo
   case cli of
     Run opts -> appMain opts
-    DocGen g -> generateDocs g
     Format fo w -> formatFile fo w
     RenderMap mapPath opts -> doRenderCmd opts mapPath
     LSP -> lspMain

app/doc/Main.hs

@@ -0,0 +1,66 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- SPDX-License-Identifier: BSD-3-Clause
+module Main where
+
+import Data.Foldable qualified
+import Data.Maybe (fromMaybe)
+import Data.Text qualified as T
+import Options.Applicative
+import Swarm.Doc.Gen (GenerateDocs (..), PageAddress (..), SheetType (..), generateDocs)
+import Swarm.Doc.Keyword (EditorType (..))
+
+cliParser :: Parser GenerateDocs
+cliParser =
+  subparser $
+    mconcat
+      [ command "recipes" (info (pure RecipeGraph) $ progDesc "Output graphviz dotfile of entity dependencies based on recipes")
+      , 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 "pedagogy" (info (pure TutorialCoverage) $ progDesc "Output tutorial coverage")
+      , command "endpoints" (info (pure WebAPIEndpoints) $ progDesc "Generate markdown Web API documentation.")
+      ]
+ where
+  editor :: Parser (Maybe EditorType)
+  editor =
+    Data.Foldable.asum
+      [ pure Nothing
+      , Just VSCode <$ switch (long "code" <> help "Generate for the VS Code editor")
+      , Just Emacs <$ switch (long "emacs" <> help "Generate for the Emacs editor")
+      ]
+  address :: Parser PageAddress
+  address =
+    let replace a b = T.unpack . T.replace a b . T.pack
+        opt n =
+          fmap (fromMaybe "") . optional $
+            option
+              str
+              ( long n
+                  <> metavar "ADDRESS"
+                  <> help ("Set the address of " <> replace "-" " " n <> ". Default no link.")
+              )
+     in PageAddress <$> opt "entities-page" <*> opt "commands-page" <*> opt "capabilities-page" <*> opt "recipes-page"
+  cheatsheet :: Parser (Maybe SheetType)
+  cheatsheet =
+    Data.Foldable.asum
+      [ pure Nothing
+      , Just Entities <$ switch (long "entities" <> help "Generate entities page (uses data from entities.yaml)")
+      , Just Recipes <$ switch (long "recipes" <> help "Generate recipes page (uses data from recipes.yaml)")
+      , Just Capabilities <$ switch (long "capabilities" <> help "Generate capabilities page (uses entity map)")
+      , Just Commands <$ switch (long "commands" <> help "Generate commands page (uses constInfo, constCaps and inferConst)")
+      , Just Scenario <$ switch (long "scenario" <> help "Generate scenario schema page")
+      ]
+
+cliInfo :: ParserInfo GenerateDocs
+cliInfo =
+  info
+    (cliParser <**> helper)
+    ( header "Swarm docs"
+        <> progDesc "Generate swarm documentation."
+        <> fullDesc
+    )
+
+main :: IO ()
+main = generateDocs =<< execParser cliInfo

src/Swarm/Doc/Gen.hs renamed to app/doc/Swarm/Doc/Gen.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE DataKinds #-}
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
 
 -- |
@@ -9,15 +10,7 @@ module Swarm.Doc.Gen (
   -- ** Main document generation function + types
   generateDocs,
   GenerateDocs (..),
-  EditorType (..),
   SheetType (..),
-  loadStandaloneScenario,
-
-  -- ** Formatted keyword lists
-  keywordsCommands,
-  keywordsDirections,
-  operatorNames,
-  builtinFunctionList,
 
   -- ** Wiki pages
   PageAddress (..),
@@ -36,6 +29,7 @@ import Data.Text (Text, unpack)
 import Data.Text qualified as T
 import Data.Text.IO qualified as T
 import Data.Tuple (swap)
+import Swarm.Doc.Keyword
 import Swarm.Doc.Pedagogy
 import Swarm.Doc.Util
 import Swarm.Doc.Wiki.Cheatsheet
@@ -47,8 +41,7 @@ import Swarm.Game.Scenario (loadStandaloneScenario)
 import Swarm.Game.World.Gen (extractEntities)
 import Swarm.Game.World.Typecheck (Some (..), TTerm)
 import Swarm.Language.Key (specialKeyNames)
-import Swarm.Language.Syntax qualified as Syntax
-import Swarm.Util (both, listEnums, quote)
+import Swarm.Util (both, listEnums)
 import Swarm.Util.Effect (simpleErrorHandle)
 import Swarm.Web (swarmApiMarkdown)
 import Text.Dot (Dot, NodeId, (.->.))
@@ -78,11 +71,6 @@ data GenerateDocs where
   WebAPIEndpoints :: GenerateDocs
   deriving (Eq, Show)
 
--- | An enumeration of the editors supported by Swarm (currently,
---   Emacs and VS Code).
-data EditorType = Emacs | VSCode | Vim
-  deriving (Eq, Show, Enum, Bounded)
-
 -- | Generate the requested kind of documentation to stdout.
 generateDocs :: GenerateDocs -> IO ()
 generateDocs = \case
@@ -133,34 +121,6 @@ generateEditorKeywords = \case
     putStr "\nsyn keyword Direction "
     T.putStrLn $ keywordsDirections Vim
 
-builtinFunctionList :: EditorType -> Text
-builtinFunctionList e = editorList e $ map constSyntax builtinFunctions
-
-editorList :: EditorType -> [Text] -> Text
-editorList = \case
-  Emacs -> T.unlines . map (("  " <>) . quote)
-  VSCode -> T.intercalate "|"
-  Vim -> T.intercalate " "
-
--- | Get formatted list of basic functions/commands.
-keywordsCommands :: EditorType -> Text
-keywordsCommands e = editorList e $ map constSyntax commands
-
--- | Get formatted list of directions.
-keywordsDirections :: EditorType -> Text
-keywordsDirections e = editorList e $ map Syntax.directionSyntax Syntax.allDirs
-
--- | A list of the names of all the operators in the language.
-operatorNames :: Text
-operatorNames = T.intercalate "|" $ map (escape . constSyntax) operators
- where
-  special :: String
-  special = "*+$[]|^"
-  slashNotComment = \case
-    '/' -> "/(?![/|*])"
-    c -> T.singleton c
-  escape = T.concatMap (\c -> if c `elem` special then T.snoc "\\\\" c else slashNotComment c)
-
 -- ----------------------------------------------------------------------------
 -- GENERATE SPECIAL KEY NAMES
 -- ----------------------------------------------------------------------------

src/Swarm/Doc/Schema/Arrangement.hs renamed to app/doc/Swarm/Doc/Schema/Arrangement.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
 
 -- |

src/Swarm/Doc/Schema/Parse.hs renamed to app/doc/Swarm/Doc/Schema/Parse.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
 
 -- |

src/Swarm/Doc/Schema/Refined.hs renamed to app/doc/Swarm/Doc/Schema/Refined.hs

@@ -26,7 +26,7 @@
 (setq swarm-font-lock-keywords
       (let* (
              ;; Generate the current keywords with:
-             ;; cabal run swarm:swarm -- generate editors --emacs
+             ;; cabal run swarm:swarm-docs -- editors --emacs
              (x-keywords '("def" "end" "let" "in" "require"))
              (x-builtins '(
                "self"

src/Swarm/Doc/Schema/Render.hs renamed to app/doc/Swarm/Doc/Schema/Render.hs

@@ -28,11 +28,11 @@
 
 ### Updating the syntax highlighting
 
-Whenever swarm language adds new features, the highlighing needs to be updated.
+Whenever swarm language adds new features, the highlighting needs to be updated.
 
-To save some time, get the current reserved words by running `swarm generate`:
+To save some time, get the current reserved words by running `swarm-docs`:
 ```bash
-cabal run swarm:swarm -- generate editors
+cabal run swarm:swarm-docs -- editors
 ```
 
 You still have to add for example types manually.

src/Swarm/Doc/Schema/SchemaType.hs renamed to app/doc/Swarm/Doc/Schema/SchemaType.hs

@@ -0,0 +1,55 @@
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- SPDX-License-Identifier: BSD-3-Clause
+--
+-- Collect keywords for documentation generation and testing.
+module Swarm.Doc.Keyword (
+  EditorType (..),
+
+  -- ** Formatted keyword lists
+  keywordsCommands,
+  keywordsDirections,
+  operatorNames,
+  builtinFunctionList,
+) where
+
+import Data.Text (Text)
+import Data.Text qualified as T
+import Swarm.Doc.Util
+import Swarm.Language.Syntax qualified as Syntax
+import Swarm.Util (quote)
+
+-- | An enumeration of the editors supported by Swarm (currently,
+--   Emacs and VS Code).
+data EditorType = Emacs | VSCode | Vim
+  deriving (Eq, Show, Enum, Bounded)
+
+builtinFunctionList :: EditorType -> Text
+builtinFunctionList e = editorList e $ map constSyntax builtinFunctions
+
+editorList :: EditorType -> [Text] -> Text
+editorList = \case
+  Emacs -> T.unlines . map (("  " <>) . quote)
+  VSCode -> T.intercalate "|"
+  Vim -> T.intercalate " "
+
+-- | Get formatted list of basic functions/commands.
+keywordsCommands :: EditorType -> Text
+keywordsCommands e = editorList e $ map constSyntax commands
+
+-- | Get formatted list of directions.
+keywordsDirections :: EditorType -> Text
+keywordsDirections e = editorList e $ map Syntax.directionSyntax Syntax.allDirs
+
+-- | A list of the names of all the operators in the language.
+operatorNames :: Text
+operatorNames = T.intercalate "|" $ map (escape . constSyntax) operators
+ where
+  special :: String
+  special = "*+$[]|^"
+  slashNotComment = \case
+    '/' -> "/(?![/|*])"
+    c -> T.singleton c
+  escape = T.concatMap (\c -> if c `elem` special then T.snoc "\\\\" c else slashNotComment c)

src/Swarm/Doc/Wiki/Cheatsheet.hs renamed to app/doc/Swarm/Doc/Wiki/Cheatsheet.hs

@@ -17,13 +17,12 @@ import Data.Tuple.Extra (both)
 import Data.Vector qualified as V
 import Graphics.Vty.Attributes.Color240
 import Linear (V2 (..))
-import Swarm.Doc.Gen (loadStandaloneScenario)
 import Swarm.Game.Display (Attribute (AWorld), defaultChar, displayAttr)
 import Swarm.Game.Entity.Cosmetic
 import Swarm.Game.Entity.Cosmetic.Assignment (terrainAttributes)
 import Swarm.Game.Location
 import Swarm.Game.ResourceLoading (initNameGenerator, readAppData)
-import Swarm.Game.Scenario (Scenario, area, scenarioCosmetics, scenarioWorlds, ul, worldName)
+import Swarm.Game.Scenario (Scenario, area, loadStandaloneScenario, scenarioCosmetics, scenarioWorlds, ul, worldName)
 import Swarm.Game.Scenario.Status (seedLaunchParams)
 import Swarm.Game.Scenario.Topography.Area (AreaDimensions (..), getAreaDimensions, isEmpty, upperLeftToBottomRight)
 import Swarm.Game.Scenario.Topography.Cell