Skip to content

Commit 15321e8

Browse files
jaredponnjaredponn
authored
Merge pull request #10 from mlabs-haskell/jared/improve-generated-documentation
Switch documentation to use `mdbook` instead of `pandoc` + general cleanup on generated documentation + added TS documentation
2 parents 58ccadf + ee54d24 commit 15321e8

File tree

9 files changed

+136
-31
lines changed

9 files changed

+136
-31
lines changed

‎README.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# flake-lang.nix
22

3-
Nix tools to help create flakes for projects
3+
Nix tools to help create flakes for projects.
44

5-
See examples [here](./examples/).
5+
## Documentation
6+
7+
- [API reference](https://mlabs-haskell.github.io/flake-lang.nix/).
8+
- [Example projects](./examples/).

‎docs/.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
book
2+
result
3+
# Ignore `src/api_reference.md` since this is built by Nix
4+
src/api_reference.md

‎docs/book.toml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[book]
2+
authors = ["LambdaBuffers Team"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"

‎docs/build.nix

Lines changed: 49 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,14 @@
22
perSystem = { pkgs, config, ... }:
33

44
# Note(jaredponn): What is going on here to generate the documentation?
5-
# Since flake-parts is using the module system and nixos also uses the
6-
# module system, we copy how they generate documentation:
7-
# - The nix function which builds the documentation
5+
# Since flake-parts is using the module system, and NixOS also uses the
6+
# module system; we copy how NixOS generates their documentation:
7+
# [1] The Nix function which builds the documentation returning an attribute
8+
# set of a bunch of goodies:
89
# https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-options-doc/default.nix
9-
# - The file where they actually build the documentation
10+
# [2] The file where NixOS builds its own documentation:
1011
# https://github.com/NixOS/nixpkgs/blob/master/doc/default.nix
1112
let
12-
# TODO(jaredponn): make this a module option or something so someone
13-
# can set this somewhere else...
1413
rootSrcUrl = "https://github.com/mlabs-haskell/flake-lang.nix/blob/master";
1514
eval =
1615
# pkgs.lib.evalModules
@@ -25,7 +24,6 @@
2524
optionsDoc = pkgs.nixosOptionsDoc {
2625
inherit (eval) options;
2726
documentType = "none";
28-
revision = "none";
2927
# We only want to include the options provided by us (there's a
3028
# bunch of extra garbage provided by flake-parts).
3129
# So, we set the attribute `.visible` to `false` for all options
@@ -73,23 +71,53 @@
7371
{
7472

7573
packages = {
76-
# Useful for debugging.
77-
docs-raw-json = optionsDoc.optionsJSON;
78-
docs-raw-common-mark = optionsDoc.optionsCommonMark;
74+
# Documentation outputs produced from [1]
75+
options-doc-json = optionsDoc.optionsJSON;
76+
options-doc-common-mark = optionsDoc.optionsCommonMark;
7977

8078
# Documentation
81-
docs = pkgs.runCommand
82-
"flake-lang-docs"
83-
{ nativeBuildInputs = [ pkgs.pandoc ]; }
84-
''
85-
pandoc ${pkgs.lib.escapeShellArg config.packages.docs-raw-common-mark} \
86-
--metadata title="flake-lang.nix" \
87-
--standalone \
88-
--output index.html
79+
docs = pkgs.stdenv.mkDerivation {
80+
name = "flake-lang-docs";
81+
nativeBuildInputs = [ pkgs.mdbook ];
8982

90-
mkdir -p "$out"
91-
mv index.html "$out"
92-
'';
83+
src = ./.;
84+
85+
OPTIONS_DOC_COMMON_MARK = config.packages.options-doc-common-mark;
86+
87+
configurePhase =
88+
''
89+
# Provide a command for linking `$OPTIONS_DOC_COMMON_MARK`
90+
# for use when in a developer shell.
91+
link-options-doc-common-mark() {
92+
2>&1 echo "link-options-doc-common-mark: creating a symbolic link named \`./src/api_reference.md\` pointing to \`\$OPTIONS_DOC_COMMON_MARK\`"
93+
ln -sf ${pkgs.lib.escapeShellArg config.packages.options-doc-common-mark} ./src/api_reference.md
94+
}
95+
96+
link-options-doc-common-mark
97+
'';
98+
99+
buildPhase =
100+
''
101+
mdbook build --dest-dir book
102+
'';
103+
104+
installPhase =
105+
''
106+
mkdir -p "$out"
107+
mv book/* "$out"
108+
'';
109+
};
110+
};
111+
112+
devShells = {
113+
docs = config.packages.docs.overrideAttrs (_self: super:
114+
{
115+
shellHook =
116+
''
117+
${super.configurePhase}
118+
'';
119+
}
120+
);
93121
};
94122
};
95123
}

‎docs/src/SUMMARY.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# flake-lang.nix
2+
3+
- [Introduction](./introduction.md)
4+
- [API Reference](./api_reference.md)

‎docs/src/introduction.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Introduction
2+
3+
This library provides a set of Nix functions to make creating flakes for
4+
languages such as Haskell, PureScript, Rust, and TypeScript easier.

‎flake-lang/build.nix

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,11 @@
7676

7777
typescriptFlake = lib.mkOption {
7878
type = lib.types.functionTo lib.types.attrs;
79-
default = import ./flake-typescript.nix pkgs;
79+
default = import ./typescript/flake-typescript.nix pkgs;
8080
readOnly = true;
81-
description = lib.mdDoc ''
82-
TODO(jaredponn): write down documentation here
83-
'';
84-
example = lib.mdDoc ''
85-
TODO(jaredponn): write down an example here
86-
'';
81+
description = lib.mdDoc builtins.readFile ./typescript/description.md;
82+
# TODO(jaredponn): add an example
83+
# example = lib.mdDoc '' '';
8784
};
8885

8986
};

‎flake-lang/typescript/description.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!-- This file is used in `../build.nix`'s `description` for TS -->
2+
3+
<!-- markdownlint-disable MD041 -->
4+
Creates a flake for a TypeScript project.
5+
6+
Returns an attribute set of the form
7+
8+
```nix
9+
{
10+
devShells."${name}-typescript" = derivation { ... };
11+
packages."${name}-typescript" = derivation { ... };
12+
packages."${name}-typescript-tgz" = derivation { ... };
13+
packages."${name}-typescript-node2nix" = derivation { ... };
14+
checks."${name}-typescript-test" = derivation { ... };
15+
}
16+
```
17+
18+
where
19+
20+
- `packages."${name}-typescript"` contains the project with a
21+
`node_modules/` provided by Nix (in the `configurePhase`), and
22+
its `buildPhase` runs `npm run "$npmBuildScript"` (where `npmBuildScript` is
23+
`build` by default).
24+
Indeed, one can overlay the entire derivation (which contains
25+
all its dependencies) to postprocess their project as they
26+
see fit. For example, one may want to generate documentation
27+
instead of building the project, by running:
28+
29+
```nix
30+
packages."${name}-typescript".overrideAttrs (_self: _super: {
31+
npmBuildScript = "docs";
32+
installPhase =
33+
''
34+
mv ./docs "$out"
35+
'';
36+
});
37+
```
38+
39+
where we assume that the `package.json` contains
40+
`scripts.docs = <some-script>` which produces documentation
41+
in the `./docs` folder.
42+
43+
- `devShells."${name}-typescript-test"` provides a developer shell with
44+
the environment variable `NODE_PATH` as the path to the
45+
`node_modules/` produced by Nix, and the command
46+
`${name}-npm-extra-dependencies` which copies the transitive
47+
closure of `npmExtraDependencies` to the folder `./extra-dependencies`.
48+
49+
Moreover, the `shellHook` will:
50+
- create a symbolic link named `node_modules` pointing to
51+
`$NODE_PATH`; and
52+
- executes `${name}-npm-extra-dependencies`.
53+
54+
- `packages."${name}-typescript-tgz"` is `packages."${name}-typescript"` except
55+
runs `npm pack` after the `buildPhase` to create a tarball of the project in
56+
the directory `$out/tarballs/`.
57+
58+
- `packages."${name}-typescript-test"` is `packages."${name}-typescript"`
59+
except it runs `npm test` after the `buildPhase` succeeding only if `npm
60+
test` succeeds.

‎flake-lang/flake-typescript.nix renamed to ‎flake-lang/typescript/flake-typescript.nix

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ pkgs.lib.makeExtensible
251251
252252
export NODE_PATH=${pkgs.lib.escapeShellArg "${npmPackage}/lib/node_modules/${srcWithNode2nixIfd.args.packageName}/node_modules"}
253253
254-
echo 'Removing existing `node_modules`, and creating a symbolic link to `$NODE_PATH` with name `node_modules`...'
254+
echo 'Removing existing `node_modules`, and creating a symbolic link named `node_modules` pointing to `$NODE_PATH`'
255255
rm -rf node_modules
256256
ln -sf "$NODE_PATH" node_modules
257257

0 commit comments

Comments
 (0)