Merge pull request #805 from avh4/haskell-lib/build-docs

Build haddock docs for elm-format-lib

.github/workflows/CI.yml

@@ -36,9 +36,10 @@ jobs:
     - name: Tests
       if: runner.os != 'Windows'
       run: |
-        ./dev/build.sh
+        ./dev/build.sh -- test
     - name: Tests (for Windows)
       if: runner.os == 'Windows'
       run: |
         ./dev/build.sh -- unit-tests
         echo "##[warning]integration tests are currently disabled on Windows CI"
+    - run: ./dev/build.sh -- docs

README.md

@@ -316,8 +316,4 @@ dev/build.sh -- build
 ./_build/elm-format
 ```
 
-### Running tests
-
-```bash
-dev/build.sh
-```
+See [`dev/Documentation`](dev/Documentation/README.md) for more contributor and build command documentation.

Shakefile/build-elm-format.cabal

@@ -27,7 +27,10 @@ executable build-elm-format
       LambdaCase
   ghc-options: -rtsopts -threaded -with-rtsopts=-I0
   build-depends:
-      base >=4.16.2.0
+      aeson >=2.0.0.0
+    , base >=4.16.2.0
     , directory >=1.3.6.2
+    , relude
     , shake >=0.19.6 && <0.20
+    , yaml
   default-language: Haskell2010

Shakefile/package.yaml

@@ -13,9 +13,12 @@ ghc-options:
   - -with-rtsopts=-I0
 
 dependencies:
+  aeson: ">= 2.0.0.0"
   base: ">= 4.16.2.0"
   directory: ">= 1.3.6.2"
   shake: ">=0.19.6 && <0.20"
+  relude: {}
+  yaml: {}
 
 
 executables:

Shakefile/src/Main.hs

@@ -50,6 +50,9 @@ rules = do
     phony "generated" $ need
         [ "generated/Build_elm_format.hs"
         ]
+    phony "docs" $ need
+        [ "_build/docs/elm-format-lib.ok"
+        ]
     phony "unit-tests" $ need
         [ "_build/cabal/elm-format-lib/test.ok"
         , "_build/cabal/elm-format-test-lib/test.ok"
@@ -60,6 +63,12 @@ rules = do
     phonyPrefix "publish-" $ \version ->
         need [ "elm-format-publish-" ++ version ]
 
+    phony "ci" $ need
+        [ "build"
+        , "test"
+        , "docs"
+        ]
+
     phony "clean" $ do
         removeFilesAfter "dist-newstyle" [ "//*" ]
         removeFilesAfter "_build" [ "//*" ]
@@ -142,3 +151,11 @@ rules = do
     Shakefiles.NestedCheckout.rules
 
     Shakefiles.Shellcheck.rules shellcheck
+
+    --
+    -- Dev tools
+    --
+
+    phony "serve:docs" $ do
+        need [ "docs" ]
+        cmd_ "simple-http-server" "--index" "_build/docs/public"

Shakefile/src/Shakefiles/Haskell.hs

@@ -10,6 +10,16 @@ import qualified Shakefiles.Platform
 import Data.Char (isSpace)
 import Data.List (dropWhileEnd, stripPrefix)
 import Shakefiles.Extra
+import System.Directory (createDirectoryIfMissing, removeDirectoryRecursive)
+import Data.Yaml (FromJSON, (.:))
+import Data.Yaml.TH (FromJSON(..))
+import qualified Data.Yaml as Yaml
+import qualified Data.Aeson.Key as Key
+import Relude.Bool.Guard (whenM)
+
+
+docsDir :: FilePath
+docsDir = "_build/docs/public"
 
 
 cabalProject :: String -> [String] -> [String] -> [String] -> [String] -> [String] -> Rules ()
@@ -33,6 +43,12 @@ cabalProject name sourceFiles sourcePatterns deps testPatterns testDeps =
             liftIO $ getHashedShakeVersion allFiles
     in
     do
+        "_build/cabal/" </> name </> "version" %> \out -> do
+            let packageYaml = name </> "package.yaml"
+            need [ packageYaml ]
+            (VersionFromYaml version) <- Yaml.decodeFileThrow packageYaml
+            writeFileChanged out version
+
         "_build/cabal/" </> name </> "build.ok" %> \out -> do
             hash <- needProjectFiles
             cmd_ "cabal" "v2-build" "-O0"  (name ++ ":libs") "--enable-tests"
@@ -58,6 +74,33 @@ cabalProject name sourceFiles sourcePatterns deps testPatterns testDeps =
             cmd_ "cabal" "v2-test" "-O0" (name ++ ":tests") "--test-show-details=streaming"
             writeFile' out ""
 
+        "_build/cabal/" </> name </> "haddock.ok" %> \out -> do
+            hash <- needProjectFiles
+            cmd_ "cabal" "v2-haddock"
+                "--haddock-html"
+                --"--haddock-for-hackage" -- broken in current haddock
+                name
+            writeFile' out hash
+
+        "_build/docs/" </> name <.> "ok" %> \out -> do
+            let haddockOk = "_build/cabal" </> name </> "haddock.ok"
+            need [ haddockOk ]
+            buildDir <- cabalBuildDir name
+            let docsBuildDir = buildDir </> "doc" </> "html" </> name
+            liftIO $ createDirectoryIfMissing True docsDir
+            let docsOutDir =  docsDir </> name
+            whenM
+                (doesDirectoryExist docsOutDir)
+                (liftIO $ removeDirectoryRecursive docsOutDir)
+            cmd_ "cp" "-r" (docsBuildDir <> "/") docsOutDir
+            copyFileChanged haddockOk out
+
+
+cabalBuildDir :: String -> Action FilePath
+cabalBuildDir projectName = do
+    version <- readFile' ("_build/cabal" </> projectName </> "version")
+    return $ "dist-newstyle" </> "build" </> Shakefiles.Platform.cabalInstallOs </> "ghc-9.2.5" </> projectName ++ "-" ++ version
+
 
 cabalBinPath :: String -> String -> FilePath
 cabalBinPath projectName opt =
@@ -169,3 +212,11 @@ executable target projectName gitDescribe =
             "publish" </> "*" </> projectName ++ "-*-" ++ show target <.> zipExt %> \out -> do
                 let source = "_build" </> "github-ci" </> "unzipped" </> takeFileName out
                 copyFileChanged source out
+
+
+newtype VersionFromYaml =
+  VersionFromYaml String
+
+instance FromJSON VersionFromYaml where
+  parseJSON = Yaml.withObject "hpack" $ \o -> VersionFromYaml
+    <$> o .: Key.fromString "version"

dev/Documentation/Build Commands.md

@@ -0,0 +1,5 @@
+
+- `dev/build.sh`: build and run tests
+- `dev/build.sh build`: build a local binary to `./_build/elm-format`
+- `dev/build.sh ci`: run all build targets that are checked on CI
+- `dev/build.sh serve:docs`: start a local HTTP server with the public Haskell API docs

dev/Documentation/README.md

@@ -1,4 +1,5 @@
 
 Documentation about the development and maintenance of elm-format itself.
 
+- [Build Commands.md](./Build Commands.md): List of useful build and dev commands
 - [Publishing.md](./Publishing.md): Instructions on how to publish a new release of elm-format

dev/build.sh

@@ -7,4 +7,4 @@ set -euo pipefail
 (cd elm-format-lib && hpack)
 (cd elm-format-test-lib && hpack)
 hpack
-exec cabal run build-elm-format:exe:build-elm-format -- --share "$@"
+exec cabal run build-elm-format:exe:build-elm-format -- "$@"

shell.nix

@@ -32,5 +32,6 @@ in haskellPackages.shellFor {
     nix-prefetch
     nodejs
     minisign
+    simple-http-server
   ];
 }