More documentation (#179)

* docs: Fix notes about .nix-tools.cache

Relates to #57

* docs: Add note about Cabal 2.4 requirement

Fixes #164

* docs: Autogenerate module option reference

* docs: Update library reference

* Buildkite: enable docs build on branches

.buildkite/pipeline.yml

@@ -15,6 +15,5 @@ steps:
     command:
       - nix-build build.nix -A maintainer-scripts.update-docs -o update-docs.sh
       - ./update-docs.sh
-    branches: master
     agents:
       system: x86_64-linux

.gitignore

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

build.nix

@@ -24,7 +24,19 @@ in {
     update-hackage = haskell.callPackage ./scripts/update-hackage.nix {};
     update-stackage = haskell.callPackage ./scripts/update-stackage.nix {};
     update-pins = haskell.callPackage ./scripts/update-pins.nix {};
-    update-docs = haskell.callPackage ./scripts/update-docs.nix {};
+    update-docs = haskell.callPackage ./scripts/update-docs.nix {
+      generatedOptions = import ./scripts/options-doc.nix {
+        # nixpkgs unstable changes "Option has no description" from an
+        # error into a warning. That is quite helpful when hardly any
+        # of our options are documented, thanks @oxij.
+        pkgs = import (pkgs.fetchFromGitHub {
+          owner = "NixOS";
+          repo = "nixpkgs";
+          rev = "4ab1c14714fc97a27655f3a6877386da3cb237bc";
+          sha256 = "16lcj9552q2jfxc27j6116qkf2vl2dcj7vhg5gdq4qi51d891yhn";
+        }) {};
+      };
+    };
     check-hydra = haskell.callPackage ./scripts/check-hydra.nix {};
   };
 }

docs/reference/commands.md

@@ -23,8 +23,10 @@ output directory, it will create a basic one with a
 
 !!! note
     If you find that there are missing files which should have been
-    generated, remove `.stack-to-nix.cache`. (There's an open issue for
-    this).
+    generated, remove `.stack-to-nix.cache`
+    (The open issue is [#57][cache-issue]).
+
+[cache-issue]: https://github.com/input-output-hk/haskell.nix/issues/57
 
 # plan-to-nix
 
@@ -58,7 +60,10 @@ Inside the output directory, there will be another directory
 generated by `cabal-to-nix`. The output file `pkgs.nix` refers to
 these files.
 
-Same note as above applies about the cache file.
+!!! note
+    If you find that there are missing files which should have been
+    generated, remove `.nix-tools.cache`
+    (The open issue is [#57][cache-issue]).
 
 # cabal-to-nix
 

docs/reference/library.md

@@ -42,18 +42,27 @@ system.
 
 ## Haskell Package description
 
-Options for building a package. (todo: more info)
+The _Haskell package descriptions_ are values of the
+`pkgSet.config.packages` attrset. These are not derivations, but just
+the configuration for building an individual package. The
+configuration options are described under `packages.<name>` in [Module
+options](./modules.md).
 
 ## Component description
 
-Options for building a component. (todo: more info)
+The _component descriptions_ are values of the
+`pkgSet.config.packages.<package>.components` attrset. These are not
+derivations, but just the configuration for building an individual
+component. The configuration options are described under
+`packages.<name>.components.*` in [Module options](./modules.md).
+
 
 ## Haskell Package
 
-A derivation which has a `components` attribute. This derivation is
-actually just for the package `Setup.hs` script, and isn't very
-interesting. To actually use the package, look within the components
-structure.
+In [Haskell.nix][], a _Haskell package_ is a derivation which has a
+`components` attribute. This derivation is actually just for the
+package `Setup.hs` script, and isn't very interesting. To actually use
+the package, look within the components structure.
 
 ```
 components = {
@@ -67,14 +76,44 @@ components = {
   
 ## Component
 
+In [Haskell.nix][], a _component_ is a derivation corresponding to a
+[Cabal component](https://www.haskell.org/cabal/users-guide/developing-packages.html)
+of a package.
+
+[Haskell.nix][] also defines a special `all` component, which is the
+union of all components in the package.
+
 ## Identifier
 
 A package identifier is an attrset pair of `name` and `version`.
 
 ## Extras
 
+Extras allow adding more packages to the package set. These will be
+functions taking a single parameter `hackage`. They should return an
+attrset of package descriptions.
+
 ## Modules
 
+Modules are the primary method of configuring building of the package
+set. They are either:
+
+1. an attrset containing [option declarations](./options.md), or
+2. a function that returns an attrset containing option declarations.
+
+If using the function form of a module, the following named parameters
+will be passed to it:
+
+| Argument         | Type | Description         | 
+|------------------|------|---------------------|
+| `haskellLib`     | attrset | The [haskellLib](#haskelllib) utility functions. |
+| `pkgs` | | The Nixpkgs collection. |
+| `pkgconfPkgs` | | A mapping of cabal build-depends names to Nixpkgs packages. (TODO: more information about this) |
+| `buildModules` | | |
+| `config` | | |
+| `options` | | |
+
+
 # Top-level attributes
 
 ## mkStackPkgSet
@@ -126,7 +165,11 @@ This is an attrset of `hsPkgs` packages from Stackage.
 
 ## haskellPackages
 
-A `hsPkgs` package set
+A `hsPkgs` package set, which is one of the recent LTS Haskell
+releases from [`snapshots`](#snapshots).
+
+The chosen LTS is updated occasionally in [Haskell.nix][], though a
+manual process.
 
 ## nix-tools
 
@@ -145,6 +188,10 @@ A derivation containing the `nix-tools` [command-line tools](commands.md).
 
 ## haskellLib
 
+Assorted functions for operating on [Haskell.nix][] data. This is
+distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell
+Infrastructure.
+
 # Package-set functions
 
 These functions exist within the `hsPkgs` package set.
@@ -152,8 +199,8 @@ These functions exist within the `hsPkgs` package set.
 ## shellFor
 
 Create a `nix-shell` [development
-environment](../user-guide/development.md) *for* developing one or
-more packages.
+environment](../user-guide/development.md) for developing one or more
+packages.
 
 ```
 shellFor =
@@ -171,7 +218,24 @@ shellFor =
 
 ## ghcWithPackages
 
+Creates a `nix-shell` [development
+environment](../user-guide/development.md) including the given
+packages selected from this package set.
+
+**Parameter**: a package selection function.
+
+**Return value**: a derivation
+
+**Example**:
+
+```
+haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])
+```
+
 ## ghcWithHoogle
 
+The same as `ghcWithPackages`, except, a `hoogle` command with a
+Hoogle documentation index of the packages will be included in the
+shell.
 
 [haskell.nix]: https://github.com/input-output-hk/haskell.nix

docs/reference/modules-preamble.md

@@ -0,0 +1,10 @@
+Haskell.nix modules options for packages and components.
+
+!!! note "Undocumented"
+    Please help write me.
+
+    This documentation is generated from Nix sources in the
+    [`modules`](https://github.com/input-output-hk/haskell.nix/tree/master/modules)
+    subdirectory.
+
+    The Markdown generation script could also be improved.

docs/reference/modules.md

@@ -1,4 +0,0 @@
-Haskell.nix modules options for packages and components.
-
-!!! note "Undocumented"
-    Please help write me.

docs/user-guide/cabal-projects.md

@@ -14,6 +14,10 @@ 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.
+
 For this example, we will run a `nix-shell` with the default GHC
 version for Nixpkgs.
 

scripts/options-doc.nix

@@ -0,0 +1,29 @@
+{ pkgs ? import <nixpkgs> {}
+, lib ? pkgs.lib
+}:
+let
+  # Provide a dummy pkg-def for the package set function
+  pkg-def = hackage: {
+    packages = {};
+    compiler = {
+      version = "";
+      nix-name = "";
+      packages = {};
+    };
+  };
+
+  # Apply the package set function to get NixOS options.
+  inherit (import ../package-set.nix { hackage = null; inherit pkgs pkg-def; }) options;
+
+  # Use code from the NixOS manual to generate Docbook XML options list.
+  manual = import (pkgs.path + /nixos/doc/manual) {
+    inherit pkgs options;
+    config.meta.doc = [];
+    version = "testing";
+    revision = "testing";
+  };
+in
+  # Convert docbook options list to markdown
+  pkgs.runCommand "options.md" {} ''
+    ${pkgs.buildPackages.pandoc}/bin/pandoc -s -f docbook -t markdown_strict ${manual.generatedSources}/options-db.xml -o $out
+  ''

scripts/update-docs.nix

@@ -1,4 +1,5 @@
-{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs }:
+{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs
+, generatedOptions }:
 
 with stdenv.lib;
 
@@ -15,6 +16,9 @@ in
 
     source ${./git.env}
 
+    echo "Preprocessing..."
+    cat docs/reference/modules-preamble.md ${generatedOptions} > docs/reference/modules.md
+
     echo "Building..."
     rm -rf site
     mkdocs build
@@ -23,6 +27,7 @@ in
     sed -i -e '/lastmod/d' site/sitemap.xml
     rm -f site/sitemap.xml.gz
     rev=$(git rev-parse --short HEAD)
+    rm docs/reference/modules.md
 
     echo "Updating git index..."
     git fetch origin