Publish docs to GitHub Pages (#15)

.github/workflows/docs.yaml

@@ -0,0 +1,28 @@
+name: "Publish Ema Docs"
+on:
+  # Run only when pushing to master branch
+  push:
+    branches:
+      - master
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: cachix/install-nix-action@v13
+        with:
+          install_url: https://nixos-nix-install-tests.cachix.org/serve/lb41az54kzk6j12p81br4bczary7m145/install
+          install_options: "--tarball-url-prefix https://nixos-nix-install-tests.cachix.org/serve"
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+      # This builds neuron, as well as run tests
+      - name: Build and generate docs HTML 🔧
+        run: |
+          nix run -- generate ./docs-output
+      - name: Deploy to GitHub Pages 🚀
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: docs-output
+          CLEAN: true

.gitignore

@@ -23,3 +23,4 @@ cabal.project.local~
 .ghc.environment.*
 result
 result-*
+docs-output/

README.md

@@ -16,6 +16,14 @@ main = do
     encodeUtf8 $ "<b>Hello</b>, from " <> name
 ```
 
+## Quick Preview
+
+If you have Nix installed with Flakes, give Ema a test-drive by running it to serve its own documentation:
+
+```bash
+PORT=8000 nix run
+```
+
 ## Hacking
 
 Run `bin/run` (or <kbd>Ctrl+Shift+B</kbd> in VSCode). This runs the clock example; modify `./.ghcid` to run a different example.

docs/Main.hs

@@ -0,0 +1,6 @@
+module Main where 
+
+import qualified Ema.Example.Ex03_Documentation as Doc
+
+main :: IO ()
+main = Doc.main

ema.cabal

@@ -113,10 +113,18 @@ library
     Ema.Server
 
   if flag(with-examples)
-    other-modules:
+    exposed-modules:
       Ema.Example.Ex01_HelloWorld
       Ema.Example.Ex02_Clock
       Ema.Example.Ex03_Documentation
 
   hs-source-dirs:     src
   default-language:   Haskell2010
+
+executable ema-docs
+  hs-source-dirs: docs
+  default-language:   Haskell2010
+  main-is: Main.hs
+  build-depends:
+    , base
+    , ema

flake.nix

@@ -11,14 +11,14 @@
   outputs = inputs@{ self, nixpkgs, flake-utils, ... }:
     flake-utils.lib.eachSystem [ "x86_64-linux" "x86_64-darwin" ] (system:
       let
+        name = "ema";
         overlays = [ ];
         pkgs = import nixpkgs {
           inherit system overlays;
         };
         emaProject = returnShellEnv:
           pkgs.haskellPackages.developPackage {
-            inherit returnShellEnv;
-            name = "ema";
+            inherit name returnShellEnv;
             root = ./.;
             withHoogle = false;
             modifier = drv:
@@ -32,12 +32,20 @@
                 haskell-language-server
               ]);
           };
+        ema = emaProject false;
       in
-      {
+      rec {
         # Used by `nix build`
-        defaultPackage = emaProject false;
+        defaultPackage = ema;
 
         # Used by `nix develop`
         devShell = emaProject true;
+
+        # Used by `nix run` (for docs)
+        apps.${name} = flake-utils.lib.mkApp {
+          drv = ema;
+          exePath = "/bin/ema-docs";
+        };
+        defaultApp = apps.${name};
       });
 }

hie.yaml

@@ -2,3 +2,5 @@ cradle:
   cabal:
     - path: "./src"
       component: "library:ema"
+    - path: "./docs"
+      component: "exe:ema-docs"