From 785de3dd705f157bc32c3747fe313ae9bc2064fc Mon Sep 17 00:00:00 2001
From: Hugo McNally <hugo.mcnally@gmail.com>
Date: Wed, 24 Jan 2024 15:49:45 +0000
Subject: [PATCH] Added the doc library

---
 .reuse/dep5   |  1 +
 flake.nix     |  5 ++++-
 lib/README.md | 30 ++++++++++++++++++++++++++++++
 lib/doc.nix   | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 lib/README.md
 create mode 100644 lib/doc.nix

diff --git a/.reuse/dep5 b/.reuse/dep5
index 747e7dc..645e9fd 100644
--- a/.reuse/dep5
+++ b/.reuse/dep5
@@ -4,5 +4,6 @@ Files: flake.lock
        pkgs/python_ot/poetry.lock
        pkgs/verilator/fix.patch
        README.md
+       **/README.md
 Copyright: lowRISC contributors
 License: MIT
diff --git a/flake.nix b/flake.nix
index a4be912..3da4221 100644
--- a/flake.nix
+++ b/flake.nix
@@ -27,7 +27,10 @@
     ...
   } @ inputs: let
     no_system_outputs = {
-      lib.poetryOverrides = import ./lib/poetryOverrides.nix;
+      lib = {
+        poetryOverrides = import ./lib/poetryOverrides.nix;
+        doc = import ./lib/doc.nix;
+      };
     };
 
     all_system_outputs = flake-utils.lib.eachDefaultSystem (system: let
diff --git a/lib/README.md b/lib/README.md
new file mode 100644
index 0000000..2d4558e
--- /dev/null
+++ b/lib/README.md
@@ -0,0 +1,30 @@
+# lowRISC Nix Libraries
+
+## The Documentation Library
+
+The `doc` library contains `buildMdbookSite`, which is a helper function for creating mdBook site builds.
+An example of it's use is below.
+
+```nix
+let
+  fs = pkgs.lib.fileset;
+in {
+  docs_build = doc.buildMdbookSite {
+    pname = "documentation";
+    version = "0.0.1";
+    nativeBuildInputs = [pkgs.python311];
+    src = fs.toSource {
+      root = ./.;
+      fileset = fs.unions [
+        (doc.standardMdbookFileset ./.)
+        ./util/mdbook
+        ./util/mdbook_wavejson.py
+      ];
+    };
+  };
+}
+```
+
+*Note: `pkgs.mdbook` is not required in nativeBuildInputs.*
+
+`standardMdbookFileset` and `hasExts` are also provided to further help in creating derivations.
diff --git a/lib/doc.nix b/lib/doc.nix
new file mode 100644
index 0000000..0217059
--- /dev/null
+++ b/lib/doc.nix
@@ -0,0 +1,33 @@
+# Copyright lowRISC Contributors.
+# Licensed under the MIT License, see LICENSE for details.
+# SPDX-License-Identifier: MIT
+{pkgs}: let
+  fs = pkgs.lib.fileset;
+  # Returns true if a file has an extension in the array `exts`.
+  hasExts = exts: file: builtins.any file.hasExt exts;
+in {
+  inherit hasExts;
+
+  standardMdbookFileset = root:
+    fs.unions [
+      (root + /book.toml)
+      (fs.fileFilter (hasExts ["md" "svg" "png"]) root)
+    ];
+
+  # A helper function to create mdBook site builds.
+  buildMdbookSite = {
+    pname,
+    version,
+    src,
+    ...
+  } @ inputs:
+    pkgs.stdenv.mkDerivation ({
+        dontFixup = true;
+        buildPhase = "${pkgs.mdbook}/bin/mdbook build";
+        installPhase = ''
+          mkdir $out
+          cp -r book/* $out
+        '';
+      }
+      // inputs);
+}