Add --format flag to spago docs (#299)

CHANGELOG.md

@@ -12,6 +12,7 @@ Bugfixes:
 
 New features:
 - Add support for starting a repl within a folder which has not been setup as a spago project (#168)
+- Add `--format` flag to `spago docs` (#294)
 
 ## [0.8.5] - 2019-06-18
 

README.md

@@ -698,6 +698,12 @@ $ spago docs
 This will generate all the documentation in the `./generated-docs` folder of your project.
 You might then want to open the `index.html` file in there.
 
+To build the documentation as Markdown instead of HTML, or to generate tags for your project,
+you can pass a `format` flag:
+```bash
+$ spago docs --format ctags
+```
+
 
 ### Publish my library
 

app/Spago.hs

@@ -19,7 +19,8 @@ import Spago.Messages as Messages
 import Spago.Packages (PackageName (..), PackagesFilter (..), JsonFlag(..))
 import qualified Spago.Packages
 import qualified Spago.PscPackage as PscPackage
-import Spago.Watch (ClearScreen (..))
+import qualified Spago.Purs as Purs
+import Spago.Watch (ClearScreen (..))
 
 
 -- | Commands that this program handles
@@ -40,7 +41,7 @@ data Command
  | Repl (Maybe Int) (Maybe CacheFlag) [PackageName] [SourcePath] [ExtraArg]
 
  -- | Generate documentation for the project and its dependencies
- | Docs [SourcePath]
+ | Docs (Maybe Purs.DocsFormat) [SourcePath]
 
  -- | Build the project paths src/ and test/ plus the specified source paths
  | Build BuildOptions
@@ -166,7 +167,7 @@ parser = do
  "transitive" -> Just TransitiveDeps
  _ -> Nothing
  in CLI.optional $ CLI.opt wrap "filter" 'f' "Filter packages: direct deps with `direct`, transitive ones with `transitive`"
-
+ docsFormat = CLI.optional $ CLI.opt Purs.parseDocsFormat "format" 'f' "Docs output format (markdown | html | etags | ctags)"
  projectCommands = CLI.subcommandGroup "Project commands:"
  [ initProject
  , build
@@ -223,7 +224,7 @@ parser = do
  docs =
  ( "docs"
  , "Generate docs for the project and its dependencies"
- , Docs <$> sourcePaths
+ , Docs <$> docsFormat <*> sourcePaths
  )
 
 
@@ -357,7 +358,7 @@ main = do
  -> Spago.Build.bundleApp WithMain modName tPath shouldBuild buildOptions
  BundleModule modName tPath shouldBuild buildOptions
  -> Spago.Build.bundleModule modName tPath shouldBuild buildOptions
- Docs sourcePaths  -> Spago.Build.docs sourcePaths
+ Docs format sourcePaths -> Spago.Build.docs format sourcePaths
  Version -> printVersion
  PscPackageLocalSetup force -> liftIO $ PscPackage.localSetup force
  PscPackageInsDhall -> liftIO $ PscPackage.insDhall

src/Spago/Build.hs

@@ -194,10 +194,10 @@ bundleModule maybeModuleName maybeTargetPath noBuild buildOpts = do
  NoBuild -> bundleAction
 
 -- | Generate docs for the `sourcePaths`
-docs :: Spago m => [Purs.SourcePath] -> m ()
-docs sourcePaths = do
+docs :: Spago m => Maybe Purs.DocsFormat -> [Purs.SourcePath] -> m ()
+docs format sourcePaths = do
  echoDebug "Running `spago docs`"
  config <- Config.ensureConfig
  deps <- Packages.getProjectDeps config
  echo "Generating documentation for the project. This might take a while.."
- Purs.docs $ Config.configSourcePaths config <> Packages.getGlobs deps <> sourcePaths
+ Purs.docs format $ Config.configSourcePaths config <> Packages.getGlobs deps <> sourcePaths

src/Spago/Purs.hs

@@ -54,13 +54,36 @@ bundle withMain (ModuleName moduleName) (TargetPath targetPath) = do
  ("Bundle failed.")
 
 
-docs :: Spago m => [SourcePath] -> m ()
-docs sourcePaths = do
+data DocsFormat
+ = Html
+ | Markdown
+ | Ctags
+ | Etags
+
+parseDocsFormat :: Text -> Maybe DocsFormat
+parseDocsFormat = \case
+ "html" -> Just Html
+ "markdown" -> Just Markdown
+ "ctags" -> Just Ctags
+ "etags" -> Just Etags
+ _ -> Nothing
+
+printDocsFormat :: DocsFormat -> Text
+printDocsFormat = \case
+ Html -> "html"
+ Markdown -> "markdown"
+ Ctags -> "ctags"
+ Etags -> "etags"
+
+
+docs :: Spago m => Maybe DocsFormat -> [SourcePath] -> m ()
+docs format sourcePaths = do
  let
  paths = Text.intercalate " " $ Messages.surroundQuote <$> map unSourcePath sourcePaths
- cmd = "purs docs " <> paths <> " --format html"
+ formatStr = printDocsFormat $ fromMaybe Html format
+ cmd = "purs docs " <> paths <> " --format " <> formatStr
  runWithOutput cmd
- ("Docs generated. Index is at " <> Messages.surroundQuote "./generated-docs/index.html")
+ "Docs generation succeeded."
  "Docs generation failed."
 
 version :: Spago m => m (Maybe Version.SemVer)