Merge pull request #65 from Liqwid-Labs/emiflake/gen-docs

expose 'options-doc' package that generates module documentation

.gitignore

@@ -1,3 +1,4 @@
 .pre-commit-config.yaml
 .direnv
 result
+book

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 This format is based on [Keep A Changelog](https://keepachangelog.com/en/1.0.0).
 
+## 2.9.2 - 2023-06-14
+
+- Add liqwid-nix module documentation generation. Both onchain and offchain have their modules included.
+  Pending implementation for automating this workstream.
+
 ## 2.9.1 - 2023-05-26
 
 - Hercules CI option is moved from `flake` to top level, by using hercules-ci-effects module.

README.md

@@ -2,18 +2,17 @@
 
 A simple library for writing nix flakes in Liqwid Labs projects. The aim of liqwid-nix is to reduce duplication of shared code, while providing a flexible escape for when real changes need to be applied.
 
-### Using direnv.
+See the [module docs](https://liqwid-labs.github.io/liqwid-nix/reference/modules.html)!
 
-Since flakes built using `liqwid-nix` provide various command-line tools that are useful for development of the projects they live in, it is useful to have them available when entering a directory. [nix-direnv](https://github.com/nix-community/nix-direnv) helps with this. Setup instructions are available in the repo README. It is not standard practice to _commit_ the `.envrc`, so you are required to create these yourself for every repository you clone. As described in the repo, it boils down to the same thing every time, `echo "use flake" > .envrc && direnv allow`.
+## Features
 
-### Using `liqwid-nix`.
+- On-chain project support using Plutarch
+- Off-chain project support using CTL
+- Overridable configuration using flake-parts
 
-This repository exposes nix templates that you can use to bootstrap your project. View the `templates` directory.
+### Using direnv.
 
-Use the following command to initialize a project using liqwid-nix:
-```sh
-nix flake init -t github:Liqwid-Labs/liqwid-nix/main
-```
+Since flakes built using `liqwid-nix` provide various command-line tools that are useful for development of the projects they live in, it is useful to have them available when entering a directory. [nix-direnv](https://github.com/nix-community/nix-direnv) helps with this. Setup instructions are available in the repo README. It is not standard practice to _commit_ the `.envrc`, so you are required to create these yourself for every repository you clone. As described in the repo, it boils down to the same thing every time, `echo "use flake" > .envrc && direnv allow`.
 
 In the case that there already is a `flake.nix` file, you must remove it or the template will refuse to be applied.
 

docs/SUMMARY.md

@@ -0,0 +1,2 @@
+- [Introduction](./index.md)
+- [Module options](./reference/modules.md)

docs/index.md

@@ -0,0 +1,9 @@
+# liqwid-nix
+
+`liqwid-nix` is a simple library for writing nix flakes in Liqwid Labs projects. The aim of liqwid-nix is to reduce duplication of shared code, while providing a flexible escape for when real changes need to be applied.
+
+## Features
+
+- On-chain project support using Plutarch
+- Off-chain project support using CTL
+- Overridable configuration using flake-parts

flake.nix

@@ -40,10 +40,23 @@
         inputs.pre-commit-hooks.flakeModule
       ];
       systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" "aarch64-linux" ];
-      perSystem = { config, self', inputs', pkgs, lib, system, ... }:
+      perSystem = { options, config, self', inputs', pkgs, lib, system, ... }:
         let
           pkgs = import inputs.nixpkgs { inherit system; };
           utils = import ./nix/utils.nix { inherit pkgs lib; };
+          doc-modules = (inputs.flake-parts.lib.evalFlakeModule
+            {
+              inherit inputs;
+            }
+            {
+              imports = [
+                ./nix/onchain.nix
+                ./nix/run.nix
+                ./nix/offchain.nix
+                # FIXME: This module doesn't seem to work yet.
+                # ./nix/ci-config.nix 
+              ];
+            });
         in
         {
           pre-commit = {
@@ -62,13 +75,25 @@
             shellHook = config.pre-commit.installationScript;
           };
           formatter = pkgs.nixpkgs-fmt;
+          packages.options-doc = (pkgs.nixosOptionsDoc { inherit (doc-modules) options; }).optionsCommonMark;
+          packages.publish-docs = pkgs.writeScript "publish-docs.sh" ''
+            rev=$(git rev-parse --short HEAD)
+            cat ${self.packages.${system}.options-doc} > ./docs/reference/modules.md
+            rm -rf book
+            ${pkgs.mdbook}/bin/mdbook build
+            touch book/.nojekyll
+            git fetch origin
+            git checkout gh-pages
+            GIT_WORK_TREE=$(pwd)/book git add -A
+          '';
 
           # This check is for `liqwid-nix` itself.
           checks.nixFormat =
             utils.shellCheck "nixFormat" ./. { nativeBuildInputs = [ pkgs.nixpkgs-fmt ]; } ''
               find -name '*.nix' -not -path './dist*/*' -not -path './haddock/*' | xargs nixpkgs-fmt
             '';
         };
+
       herculesCI = {
         ciSystems = [ "x86_64-linux" ];
         onPush.default.outputs = self.checks.x86_64-linux;

nix/offchain.nix

@@ -348,14 +348,8 @@ in
                 default = false;
               };
 
-              nodejsPackage = lib.mkOption {
-                description = ''
-                  The nodejs package to use.
-
-                  Added in: 2.1.1.
-                '';
-                type = types.package;
-                default = pkgs.nodejs-14_x;
+              nodejsPackage = lib.mkPackageOption pkgs "nodejs" {
+                default = [ "nodejs-14_x" ];
               };
             };
           };