From 1f1ec8bc9f26a5d4e6c2a6388ea88619b3a3d948 Mon Sep 17 00:00:00 2001 From: Elliot Davies Date: Mon, 1 Jul 2019 12:26:46 +0100 Subject: [PATCH 1/3] Initial work on adding docs flag --- app/Spago.hs | 11 ++++++----- src/Spago/Build.hs | 6 +++--- src/Spago/Purs.hs | 29 ++++++++++++++++++++++++++--- 3 files changed, 35 insertions(+), 11 deletions(-) diff --git a/app/Spago.hs b/app/Spago.hs index d8e53274b..0307afe6f 100644 --- a/app/Spago.hs +++ b/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 diff --git a/src/Spago/Build.hs b/src/Spago/Build.hs index 8f93473d4..07480327a 100644 --- a/src/Spago/Build.hs +++ b/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 diff --git a/src/Spago/Purs.hs b/src/Spago/Purs.hs index 0408f2ca8..742ec9b34 100644 --- a/src/Spago/Purs.hs +++ b/src/Spago/Purs.hs @@ -54,11 +54,34 @@ 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 failed." From a2f8feeacdee15d91ef411e51bfc132cb4dda513 Mon Sep 17 00:00:00 2001 From: Elliot Davies Date: Mon, 1 Jul 2019 13:57:20 +0100 Subject: [PATCH 2/3] Update changelog and readme --- CHANGELOG.md | 1 + README.md | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c11c1438..1653b2673 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index cc5c064d1..50440b05f 100644 --- a/README.md +++ b/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 From 9d8f8d7b92ea96404d6a4fe359833850a8851e15 Mon Sep 17 00:00:00 2001 From: Elliot Davies Date: Mon, 1 Jul 2019 19:29:56 +0100 Subject: [PATCH 3/3] Succeed more generally --- src/Spago/Purs.hs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Spago/Purs.hs b/src/Spago/Purs.hs index 742ec9b34..5dc833623 100644 --- a/src/Spago/Purs.hs +++ b/src/Spago/Purs.hs @@ -83,7 +83,7 @@ docs format sourcePaths = do 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)