Add documentation

.github/workflows/ci.yaml

@@ -46,3 +46,27 @@ jobs:
       - name: Run test
         id: test
         run: ./runtest.sh
+
+  www:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - uses: actions/checkout@v2
+      - uses: cachix/install-nix-action@v18
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
+      - uses: cachix/cachix-action@v11
+        with:
+          name: srid
+      - name: Build the website
+        run: |
+          mkdir ./www
+          nix --accept-flake-config run github:srid/emanote -- -L ./doc gen ./www
+      - name: Deploy to gh-pages 🚀
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./www/
+          cname: haskell.flake.page

README.md

@@ -4,7 +4,8 @@ A [`flake-parts`](https://flake.parts/) Nix module for Haskell development.
 
 ## Why?
 
-To keep `flake.nix` smaller (see examples below) and declarative ([what](https://github.com/srid/emanote-template/blob/c955a08fa685adb2fb81c4d8cefac6e20f417fee/flake.nix#L19-L26) vs [how](https://github.com/srid/emanote-template/blob/78d64b6e1e3497e3bd97012d8bf6f8bd6ec9cdd3/flake.nix#L19-L57)) by bringing a NixOS-like [module system](https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules) to flakes (through `flake-parts`).
+To keep `flake.nix` smaller (see examples below) and declarative ([what](https://github.com/srid/emanote-template/blob/c955a08fa685adb2fb81c4d8cefac6e20f417fee/flake.nix#L19-L26) vs [how](https://github.com/srid/emanote-template/blob/78d64b6e1e3497e3bd97012d8bf6f8bd6ec9cdd3/flake.nix#L19-L57)) by bringing a NixOS-like [module system](https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules) to flakes. 
+ `haskell-flake` simply uses [`callCabal2nix` and `shellFor`](https://github.com/srid/haskell-multi-nix/blob/nixpkgs/flake.nix) under the hood.
 
 ## Usage
 
@@ -26,7 +27,8 @@ You may also use https://github.com/srid/haskell-template which already uses `ha
 
 ## Documentation
 
-Check out the [list of options](https://flake.parts/options/haskell-flake.html). `haskell-flake` uses [`callCabal2nix` and `shellFor`](https://github.com/srid/haskell-multi-nix/blob/nixpkgs/flake.nix) under the hood.
+https://haskell.flake.page/
+
 
 ## Examples
 

doc/howto.md

@@ -0,0 +1,6 @@
+
+# HOWTO
+
+```query
+path:./*
+```

doc/howto/dependency.md

@@ -0,0 +1,51 @@
+---
+slug: dependency
+---
+
+# Adding dependencies
+
+There are several libraries from [Hackage](https://hackage.haskell.org/) that you can use in your Haskell project nixified using haskell-flakea. The general steps to do this are:
+
+1. Identify the package name from Hackage. Let's say you want to use [`ema`](https://hackage.haskell.org/package/ema)
+2. Add the package, `ema`, to the `.cabal` file under [the `build-depends` section](https://cabal.readthedocs.io/en/3.4/cabal-package.html#pkg-field-build-depends).
+3. Exit and restart the nix shell (`nix develop`). 
+
+Step (3) above will try to fetch the package from the Haskell package set in [nixpkgs](https://github.com/NixOS/nixpkgs) (the one that is pinned in `flake.lock`), and this package set (which is ultimately derived from Stackage sets) sometimes may not have the package you are looking for. A common reason is that it is marked as "broken" or it simply doesn't exist. In such cases, you will have to override the package in the `overrides` argument (see the next section).
+
+## Overriding a Haskell package in Nix
+
+In Nix, it is possible to use an exact package built from an arbitrary source (Git repo or local directory). If you want to use the `master` branch of the [ema](https://hackage.haskell.org/package/ema) library, for instance, you can do it as follows:
+
+1. Add a flake input pointing to the ema Git repo in `flake.nix`: 
+    ```nix
+    {
+      inputs = {
+        ema = {
+          url = "github:EmaApps/ema";
+          flake = false;
+        };
+      };
+    }
+    ```
+1. Build it using `callCabal2nix` and assign it to the `ema` name in the Haskell package set by adding it to the `overrides` argument of your `flake.nix` that is using haskell-flake:
+    ```nix
+    {
+      perSystem = { self', config, pkgs, ... }: {
+        haskellProjects.default = {
+          overrides = self: super: with pkgs.haskell.lib; {
+            ema = dontCheck (self.callCabal2nix "ema" inputs.ema {}); 
+          };
+        };
+      };
+    }
+    ```
+    We use `dontCheck` here to disable running tests. You can also use `source-overrides` instead of `overrides`.
+1. Re-run the nix shell (`nix develop`).
+
+## `pkgs.haskell.lib` functions
+
+- [ ] Write about https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/lib/compose.nix
+
+## See also
+
+- [Artyom's tutorial](https://tek.brick.do/how-to-override-dependency-versions-when-building-a-haskell-project-with-nix-K3VXJd8mEKO7) 

doc/index.md

@@ -0,0 +1,5 @@
+# haskell-flake
+
+https://github.com/srid/haskell-flake
+
+Start from [[howto]] or the [module options](https://flake.parts/options/haskell-flake.html).

doc/index.yaml

@@ -0,0 +1,20 @@
+page:
+  siteTitle: haskell-flake
+  siteName: haskell-flake
+  headHtml: |
+    <snippet var="js.highlightjs" />
+
+template:
+  name: /templates/layouts/book
+
+  theme: purple
+  # iconUrl: static/favicon.jpeg
+  sidebar:
+    collapsed: true
+  urlStrategy: pretty
+
+pandoc:
+  rewriteClass:
+    prose: max-w-prose mx-auto
+    page-note: text-sm text-gray-600 flex items-center justify-center my-4 italic
+    editor-note: text-gray-500 text-sm