docs/lib: init

Generate reference docs for functions that have RFC145 style
doc-comments.

1. function locations

  `docs/lib/function-locations.nix` scans nixvim's extended lib,
  extracting "position entries" via `unsafeGetAttrPos`.

  This is then converted into a nixdoc `locations.json` map of
  "function name" → "markdown location string".

2. mdbook menu

  `docs/lib/menu.nix` renders a mdbook menu representing all page
  entries.

3. markdown pages

  `docs/lib/default.nix` expects a set of "page entries", which come
  from `docs/lib/pages.nix` by default. It passes this data to
  `function-locations.nix` and `menu.nix`, and uses it internally to
  render markdown pages.

  Page entries can contain a `file` to render using `nixdoc`, and also a
  `markdown` attribute which will be included at the top of the docs.

  Additionally, a `title` can be included. This forms the heading
  `$name: $title`, where `name` is derived from the page's attr-path.

  See https://github.com/nix-community/nixdoc

docs/lib/menu.nix

@@ -0,0 +1,31 @@
+{
+  lib,
+  pageSpecs,
+  indentSize ? "  ",
+}:
+let
+  pageToLines =
+    indent: parentName:
+    {
+      name,
+      outFile ? "",
+      pages ? { },
+      ...
+    }:
+    let
+      menuName = lib.strings.removePrefix (parentName + ".") name;
+      children = builtins.attrValues pages;
+      # Only add node to the menu if it has content or multiple children
+      useNodeInMenu = outFile != "" || builtins.length children > 1;
+      parentOfChildren = if useNodeInMenu then name else parentName;
+    in
+    lib.optional useNodeInMenu "${indent}- [${menuName}](${outFile})"
+    ++ lib.optionals (children != [ ]) (
+      builtins.concatMap (pageToLines (indent + indentSize) parentOfChildren) children
+    );
+in
+lib.pipe pageSpecs [
+  builtins.attrValues
+  (builtins.concatMap (pageToLines "" ""))
+  lib.concatLines
+]