Fix #518: examples in documentation need to be tested (#1714)

Author: yvan-sraka

.buildkite/pipeline.yml

@@ -74,6 +74,11 @@ steps:
     agents:
       system: x86_64-linux
 
+  - label: 'Test examples in documentation ...'
+    command: "./test/tests.sh ghc8107 docs"
+    agents:
+      system: x86_64-linux
+
   - label: 'Check that jobset will evaluate in Hydra at ifdLevel 0 and 1'
     command:
       - nix-build build.nix -A maintainer-scripts.check-hydra -o check-hydra.sh

.gitignore

@@ -1,6 +1,7 @@
-# The output of "mkdocs build"
-/site/
-docs/reference/modules.md
+# The output of "mdbook build"
+/book/
+/docs/reference/modules.md
+/docs/**/index.html
 
 # Nix build results
 result*

book.toml

@@ -0,0 +1,5 @@
+[book]
+language = "en"
+multilingual = false
+src = "docs"
+title = "Alternative Haskell Infrastructure for Nixpkgs"

docs/SUMMARY.md

@@ -0,0 +1,38 @@
+- [Introduction](./index.md)
+- [Motivation](./motivation.md)
+- [Architecture](./architecture.md)
+- [Tutorials](./tutorials/index.md)
+    - [Getting started](./tutorials/getting-started.md)
+    - [Getting started with Flakes](./tutorials/getting-started-flakes.md)
+    - [Getting started with Hix](./tutorials/getting-started-hix.md)
+    - [Creating a development environment](./tutorials/development.md)
+    - [Sourcing files only part of git repository using cleanGit](./tutorials/clean-git.md)
+    - [Handling git repositories in projects](./tutorials/source-repository-hashes.md)
+    - [Mapping non-Haskell dependencies to Nixpkgs](./tutorials/pkg-map.md)
+    - [Bumping Hackage and Stackage snapshots](./tutorials/hackage-stackage.md)
+    - [Materialization: Speeding up Nix evaluation](./tutorials/materialization.md)
+    - [Cross-compiling your project](./tutorials/cross-compilation.md)
+    - [Generating coverage information](./tutorials/coverage.md)
+    - [Build a specific package from Hackage or Stackage](./tutorials/building-package-from-stackage-hackage.md)
+    - [Content addressed derivations](./tutorials/ca-derivations.md)
+- [Reference](./reference/index.md)
+    - [Supported GHC versions](./reference/supported-ghc-versions.md)
+    - [Command-line tools](./reference/commands.md)
+    - [Haskell.nix Library](./reference/library.md)
+    - [Module options](./reference/modules.md)
+    - [Troubleshooting](./troubleshooting.md)
+- [Templates / Abstraction](./template/index.html)
+    - [IOHKs nix library](./template/iohk-nix.md)
+- [Dev Notes](./dev/index.html)
+    - [Architecture](./dev/dev-architecture.md)
+    - [Installing nix-tools](./dev/installing-nix-tools.md)
+    - [How to update nix-tools](./dev/nix-tools-pin.md)
+    - [Manually generating Nix expressions](./dev/manually-generating-nix-expressions.md)
+    - [Maintainer Scripts](./dev/maintainer-scripts.md)
+    - [Nixpkgs Pin](./dev/nixpkgs-pin.md)
+    - [Removing withPackage wrapper](./dev/removing-with-package-wrapper.md)
+    - [Test Suite](./dev/tests.md)
+    - [Adding a new GHC version](./dev/adding-new-ghc.md)
+    - [Coverage](./dev/coverage.md)
+    - [Making changes to Hix](./dev/hix.md)
+    - [ChangeLog](./changelog.md)

docs/dev/adding-new-ghc.md

@@ -16,7 +16,7 @@ Check the LLVM version that should be used in the
 
 In the haskell.nix repo run:
 
-```
+```shell
 mkdir materialized/ghc884
 nix-build scripts/check-compiler-materialization --argstr compiler-nix-name ghc884
 ```

docs/dev/coverage.md

@@ -52,7 +52,7 @@ reports (as detailed in the [coverage tutorial](../tutorials/coverage.md#custom)
 
 The coverage information generated will look something like this:
 
-```bash
+```shell
 /nix/store/...-my-project-0.1.0.0-coverage-report/
 └── share
     └── hpc
@@ -105,7 +105,7 @@ The coverage information generated will look something like this:
 The coverage information for an entire project will look something
 like this:
 
-```bash
+```shell
 /nix/store/...-coverage-report
 └── share
     └── hpc

docs/dev/hix.md

@@ -7,21 +7,21 @@ test the changes locally before uploading them to github.
 
 Install the hix command wrappers after making changes to a local clone of haskell.nix:
 
-```
+```shell
 nix-env -iA hix -f /path/to/local/haskell.nix
 hix-shell
 ```
 
 Or override the version of haskell.nix used by the commands with the `HIX_ROOT` environment variable:
 
-```
+```shell
 HIX_ROOT=/path/to/local/haskell.nix hix-shell
 ```
 
 ## Flakes
 
 For flakes use `--override-input` to point to the modified haskell.nix:
 
-```
+```shell
 nix develop --override-input haskellNix /path/to/local/haskell.nix
 ```

docs/dev/index.md

@@ -2,13 +2,13 @@
 
 To build the latest `nix-tools` and store the result at `./nt`, run:
 
-```bash
+```shell
 nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz pkgs.haskell-nix.nix-tools.ghc884 --out-link nt
 ```
 
 If you would like to then install `nix-tools` into your profile, run:
 
-```bash
+```shell
 nix-env -i ./nt
 ```
 
@@ -18,7 +18,7 @@ The [Haskell.nix][] and `nix-tools` source will be useful if you would
 like to contribute improvements, or read the source code to fully
 understand something that the documentation doesn't cover.
 
-```bash
+```shell
 git clone https://github.com/input-output-hk/nix-tools
 git clone https://github.com/input-output-hk/haskell.nix
 cd haskell.nix

docs/dev/installing-nix-tools.md

@@ -8,11 +8,13 @@ scripts in this repo.
 
 To run the updater scripts manually, use:
 
-    nix-build build.nix -A maintainer-scripts.update-hackage -o update-hackage.sh
-    ./update-hackage.sh
+```shell
+nix-build build.nix -A maintainer-scripts.update-hackage -o update-hackage.sh
+./update-hackage.sh
 
-    nix-build build.nix -A maintainer-scripts.update-stackage -o update-stackage.sh
-    ./update-stackage.sh
+nix-build build.nix -A maintainer-scripts.update-stackage -o update-stackage.sh
+./update-stackage.sh
+```
 
 The scripts will clone the repo, generate the latest data, then
 attempt to push back to the repo and update the source JSON file.

docs/dev/maintainer-scripts.md

@@ -19,62 +19,19 @@ Let us assume for now that we have already generated a `pkgs.nix`
 expression (see the links bellow). The following file then produces a package set:
 
 ```nix
-# default.nix
-let
-  # Import the Haskell.nix library,
-  pkgs = import <nixpkgs> (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs;
-
-  # Import the file you will create in the stack-to-nix or cabal-to-nix step.
-  my-pkgs = import ./pkgs.nix;
-
-  # Stack projects use this:
-  pkgSet = pkgs.haskell-nix.mkStackPkgSet {
-    stack-pkgs = my-pkgs;
-    pkg-def-extras = [
-      # these extras will provide additional packages
-      # ontop of the package set.  E.g. extra-deps
-      # for stack packages. or local packages for
-      # cabal.projects
-    ];
-    modules = [
-      # specific package overrides would go here
-      # example:
-      #  packages.cbors.package.ghcOptions = "-Werror";
-      #  packages.cbors.patches = [ ./one.patch ];
-      #  packages.cbors.flags.optimize-gmp = false;
-      # It may be better to set flags in stack.yaml instead
-      # (`stack-to-nix` will include them as defaults).
-    ];
-  };
-
-  # Cabal projects use this:
-  pkgSet = pkgs.haskell-nix.mkCabalProjectPkgSet {
-    plan-pkgs = my-pkgs;
-    pkg-def-extras = [];
-    modules = [
-      # specific package overrides would go here
-      # example:
-      #  packages.cbors.package.ghcOptions = "-Werror";
-      #  packages.cbors.patches = [ ./one.patch ];
-      #  packages.cbors.flags.optimize-gmp = false;
-      # It may be better to set flags in `cabal.project` instead
-      # (`plan-to-nix` will include them as defaults).
-    ];
-  };
-
-in pkgSet.config.hsPkgs // { _config = pkgSet.config; }
+{{#include manually-generating-nix-expressions/default.nix}}
 ```
 
 With this setup you can then start building the components of
 interest:
 
-```bash
+```shell
 nix build -f default.nix $pkg.components.library
 ```
 
 to build the library for `$pkg` or
 
-```bash
+```shell
 nix build -f default.nix $pkg.components.exes.$exe
 ```
 
@@ -85,7 +42,7 @@ to build a specific executable. The same holds for test suites and benchmarks.
 With [nix-tools installed](./installing-nix-tools.md), we can simply run the
 following command on a stack project:
 
-```bash
+```shell
 stack-to-nix --output . --stack-yaml stack.yaml
 ```
 
@@ -121,34 +78,36 @@ about how to choose a specific compiler version.
 
 [compiler]: https://nixos.org/nixpkgs/manual/#how-to-install-a-compiler
 
-!!! note "Cabal version"
-    The minimum Cabal version is 2.4. This version is available
-    in the NixOS 19.03 release.
+> **Note:** Cabal version
+>
+> The minimum Cabal version is 2.4. This version is available
+> in the NixOS 19.03 release.
 
 For this example, we will run a `nix-shell` with the default GHC
 version for Nixpkgs.
 
-```bash
+```shell
 nix-shell -p haskellPackages.cabal-install haskellPackages.ghc \
     --run "cabal new-configure"
 ```
 
 If all goes well, you should now have the file
 `dist-newstyle/cache/plan.json`.
 
-!!! tip "Specifying the GHC version"
-    To use a specific compiler version, replace `haskellPackages.ghc`
-    with something like `haskell-nix.compiler.ghc865`. The given compiler
-    must exist in your Nixpkgs version, of course. See also the
-    [Nixpkgs Manual][compiler].
+> **Tip:** Specifying the GHC version
+>
+> To use a specific compiler version, replace `haskellPackages.ghc`
+> with something like `haskell-nix.compiler.ghc865`. The given compiler
+> must exist in your Nixpkgs version, of course. See also the
+> [Nixpkgs Manual][compiler].
 
 ### Using `plan-to-nix`
 
 With [nix-tools installed](./installing-nix-tools.md), we can then run the
 following command on a Cabal project and its build plan. Omit the
 `--cabal-project` option if you don't have a project file.
 
-```bash
+```shell
 # convert the plan.json file into a pkgs.nix file
 plan-to-nix --output . \
     --plan-json dist-newstyle/cache/plan.json

docs/dev/manually-generating-nix-expressions.md

@@ -0,0 +1,44 @@
+# default.nix
+let
+  # Import the Haskell.nix library,
+  pkgs = import <nixpkgs> (import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}).nixpkgsArgs;
+
+  # Import the file you will create in the stack-to-nix or cabal-to-nix step.
+  my-pkgs = import ./pkgs.nix;
+
+  # Stack projects use this:
+  # pkgSet = pkgs.haskell-nix.mkStackPkgSet {
+  #   stack-pkgs = my-pkgs;
+  #   pkg-def-extras = [
+  #     # these extras will provide additional packages
+  #     # ontop of the package set.  E.g. extra-deps
+  #     # for stack packages. or local packages for
+  #     # cabal.projects
+  #   ];
+  #   modules = [
+  #     # specific package overrides would go here
+  #     # example:
+  #     #  packages.cbors.package.ghcOptions = "-Werror";
+  #     #  packages.cbors.patches = [ ./one.patch ];
+  #     #  packages.cbors.flags.optimize-gmp = false;
+  #     # It may be better to set flags in stack.yaml instead
+  #     # (`stack-to-nix` will include them as defaults).
+  #   ];
+  # };
+
+  # Cabal projects use this:
+  pkgSet = pkgs.haskell-nix.mkCabalProjectPkgSet {
+    plan-pkgs = my-pkgs;
+    pkg-def-extras = [];
+    modules = [
+      # specific package overrides would go here
+      # example:
+      #  packages.cbors.package.ghcOptions = "-Werror";
+      #  packages.cbors.patches = [ ./one.patch ];
+      #  packages.cbors.flags.optimize-gmp = false;
+      # It may be better to set flags in `cabal.project` instead
+      # (`plan-to-nix` will include them as defaults).
+    ];
+  };
+
+in pkgSet.config.hsPkgs // { _config = pkgSet.config; }

docs/dev/manually-generating-nix-expressions/default.nix

@@ -0,0 +1 @@
+# FIXME

docs/dev/manually-generating-nix-expressions/pkgs.nix

@@ -1,13 +1,13 @@
 ## How to update [`nix-tools`](https://github.com/input-output-hk/nix-tools)
 
 1. Use niv to update the sources.json:
-   ```
+   ```shell
    nix flake lock --update-input nix-tools
    ```
 
 2. If `nix-tools.cabal` or `plan-to-nix` have changed, check the
    materialized files for each of the compiler nix name in
    `ls -d materialized/ghc*/nix-tools` with:
-   ```
+   ```shell
    nix-build scripts/check-compiler-materialization --argstr compiler-nix-name ghc884
    ```