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.