mirror of
https://github.com/ilyakooo0/haskell.nix.git
synced 2024-09-11 06:55:40 +03:00
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
This commit is contained in:
parent
7d94fe2ef5
commit
e15f235319
@ -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
|
||||
|
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,5 +1,6 @@
|
||||
# The output of "mkdocs build"
|
||||
/site/
|
||||
docs/reference/modules.md
|
||||
|
||||
# Nix build results
|
||||
result*
|
||||
|
14
build.nix
14
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 {};
|
||||
};
|
||||
}
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
10
docs/reference/modules-preamble.md
Normal file
10
docs/reference/modules-preamble.md
Normal file
@ -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.
|
@ -1,4 +0,0 @@
|
||||
Haskell.nix modules options for packages and components.
|
||||
|
||||
!!! note "Undocumented"
|
||||
Please help write me.
|
@ -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.
|
||||
|
||||
|
29
scripts/options-doc.nix
Normal file
29
scripts/options-doc.nix
Normal file
@ -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
|
||||
''
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user