Update the docs

Author: rvl

.gitignore

@@ -1,3 +1,9 @@
+# The output of "mkdocs build"
+/site/
+
+# Nix build results
+result*
+/nt
 
 # Created by https://www.gitignore.io/api/haskell,emacs,vim
 

changelog.md

@@ -1,3 +1,9 @@
+This file contains a summary of changes to Haskell.nix and `nix-tools`
+that will impact users.
+
+## June 6, 2019
+  * Substantial additions to the [documentation](https://input-output-hk.github.io/haskell.nix/).
+
 ## May 29, 2019
   * Added `shellFor` function to package set.
 
@@ -8,7 +14,7 @@
 ## May 22, 2019
   * Add the `cleanSourceHaskell` utility function to the Haskell.nix
     top-level.
-  
+
 ## May 21, 2019
   * Add the `callCabalProjectToNix` function, which uses "import from
     derivation" (IFD) so that nix-tools doesn't need to be run
@@ -23,7 +29,13 @@
   * Add the `callStackToNix` function, which uses "import from
     derivation" (IFD) so that `stack-to-nix` doesn't need to be run
     manually.
-  
+
 ## Mar 15, 2019
-  * overlays was renamed to extras (#79)
-    See docs/migration.md
+  * `overlays` was renamed to `extras` in
+    [#79](https://github.com/input-output-hk/haskell.nix/pull/79)
+    to prevent confusion between the notion of Nix overlays.
+
+    Therefore `plan-pkgs` and `stack-pkgs` as generated by `plan-to-nix` and `stack-to-nix` will
+    expose `extras` instead of `overlay`. Similarly `mkStackPkgSet`, `mkPkgSet` and `mkCabalProjectPkgSet`
+    take a `pkg-def-extras` instead of `pkg-def-overlay` argument.  If you are using `iohk-nix`, the
+    `iohk-overlay` was parameter was renamed to `iohk-extras`.

docs/architecture.md

@@ -43,22 +43,26 @@ nix-tools is a Haskell package that provides the following tools:
 
 as well as a few other tools used to generate `hackage.nix` and `stackage.nix`.
 
-## [haskell.nix](https://github.com/input-output-hk/haskell.nix)
+## [haskell.nix][]
 
-haskell.nix is the runtime system for this Haskell infrastructure.  It
-contains the component builder, as well as the system package and
+[Haskell.nix][] is the runtime system for this Haskell infrastructure.
+It contains the component builder, as well as the system package and
 license mapping.  Without haskell.nix the expressions generated by
 either of the `nix-tools` tools make little sense on their own.
 
-## [hackage.nix](https://github.com/input-output-hk/hackage.nix)
+## [hackage.nix][]
 
-hackage.nix provides all cabal expressions from hackage as nix
+[hackage.nix][] provides all cabal expressions from hackage as nix
 expressions.  It is periodically updated to keep in sync with the set
 of packages available on hackage.
 
-## [stackage.nix](https://github.com/input-output-hk/stackage.nix)
+## [stackage.nix][]
 
-stackage.nix is similar to hackage.nix but provides all stackage
+[stackage.nix][] is similar to hackage.nix but provides all stackage
 snapshots (lts, and nightly) as nix expressions.  It naturally depends
 on hackage.nix to resolve package names, versions and revisions to the
 repsective packages from hackage.nix.
+
+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
+[hackage.nix]: https://github.com/input-output-hk/hackage.nix
+[stackage.nix]: https://github.com/input-output-hk/stackage.nix

docs/changelog.md

@@ -0,0 +1 @@
+../changelog.md

docs/index.md

@@ -1,7 +1,11 @@
 # haskell.nix
 
 haskell.nix is an alternative Haskell infrastructure for nixpkgs. See
-[Nixpkgs current Users' Guide to Haskell Infrastructure](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) for comparison.
+[Nixpkgs current Users' Guide to Haskell Infrastructure][nixpkgs] for
+comparison.
+
+[nixpkgs]: https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure
+[issues]: https://github.com/input-output-hk/haskell.nix/issues
 
 ## Motivation