Merge #171

171: Add more docs r=roberth a=woile

This PR adds the following:

- an examples folder
- an example for devShell
- templates are no longer marked as examples, now there are templates and examples avoiding confusion

#170 

Co-authored-by: Santiago Fraire <[email protected]>
Co-authored-by: Robert Hensing <[email protected]>

README.md

@@ -3,12 +3,18 @@
 
 _Core of a distributed framework for writing Nix Flakes._
 
-`flake-parts` provides the options that represent standard flake attributes 
+`flake-parts` provides the options that represent standard flake attributes
 and establishes a way of working with `system`.
 Opinionated features are provided by an ecosystem of modules that you can import.
 
 `flake-parts` _itself_ has the goal to be a minimal mirror of the Nix flake schema.
-Used by itself, it is very lightweight. 
+Used by itself, it is very lightweight.
+
+---
+
+**Documentation**: [flake.parts](https://flake.parts)
+
+---
 
 # Why Modules?
 
@@ -71,14 +77,22 @@ then slide `mkFlake` between your outputs function head and body,
 
 Now you can add the remaining module attributes like in the [the template](./template/default/flake.nix).
 
-# Example
+# Templates
 
 See [the template](./template/default/flake.nix).
 
-# Options Reference
+# Examples
 
-See [flake.parts options](https://flake.parts/options/flake-parts.html)
+See the [examples/](./examples) directory.
 
-# Documentation
+# Projects using flake-parts
 
-See [flake.parts](https://flake.parts)
+- [nixd](https://github.com/nix-community/nixd/blob/main/flake.nix) (c++)
+- [hyperswitch](https://github.com/juspay/hyperswitch/blob/main/flake.nix) (rust)
+- [argo-workflows](https://github.com/argoproj/argo-workflows/blob/master/dev/nix/flake.nix) (go)
+- [nlp-service](https://github.com/recap-utr/nlp-service/blob/main/flake.nix) (python)
+- [emanote](https://github.com/srid/emanote/blob/master/flake.nix) (haskell)
+
+# Options Reference
+
+See [flake.parts options](https://flake.parts/options/flake-parts.html)

examples/project-commands/Hello.avdl

@@ -0,0 +1,6 @@
+protocol Hello {
+    record Hello {
+        string message;
+        int timestamp;
+    }
+}

examples/project-commands/README.md

@@ -0,0 +1,42 @@
+# project-commands
+
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
+This example shows how to create scripts for your project, by leveraging [mission-control](https://github.com/Platonic-Systems/mission-control)
+
+This is a **potential** alternative to:
+
+- Using a `Makefile` to manage your project's scripts
+- Using the popular [Scripts To Rule Them All](https://github.com/github/scripts-to-rule-them-all); a naming convention for a `scripts/` directory
+- Using a `bin/` directory
+
+## Explanation
+
+In this example we use the [avro-tools](https://avro.apache.org/) to convert our scripts from `.avdl` to `.avsc`.
+
+You don't need to know anything about avro to understand mission-control and use this example (that's Nix baby 🚀).
+
+When setting up [mission-control](https://github.com/Platonic-Systems/mission-control), we add
+one script called `build`. Because of `wrapperName = "run";`, once we open the shell created by nix,
+the commands will be listed as `run build`.
+
+mission-control depends on flake-root, which also exposes the helpful `$FLAKE_ROOT` variable.
+
+After creating the scripts, we need to pass the newly created scripts to the desired shell, in this example we use the default shell.
+
+## Usage
+
+Run:
+
+```sh
+nix develop
+```
+
+And mission-control will print in the new shell the available commands (you should see only one).
+
+Try running
+
+```sh
+run build
+```

examples/project-commands/flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    mission-control.url = "github:Platonic-Systems/mission-control";
+    flake-root.url = "github:srid/flake-root";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.mission-control.flakeModule
+        inputs.flake-root.flakeModule
+      ];
+      systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, self', inputs', pkgs, system, ... }: {
+        devShells.default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ avro-tools ];
+          inputsFrom = [ config.mission-control.devShell config.flake-root.devShell ];
+        };
+        mission-control = {
+          wrapperName = "run";
+          scripts = {
+            build = {
+              description = "convert files from .avdl to .avsc";
+              exec = ''
+                avro-tools idl2schemata "$FLAKE_ROOT/Hello.avdl" .
+              '';
+              category = "Development";
+            };
+          };
+        };
+      };
+    };
+}

examples/shell-environments/README.md

@@ -0,0 +1,55 @@
+# shell-environment
+
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
+This example shows how to create a shell environment which
+includes a diverse set of tools:
+
+```sh
+terraform
+wget
+bat
+nixpkgs-fmt
+```
+
+You can search for more packages in [nix packages](https://search.nixos.org/packages)
+
+## Usage
+
+The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command:
+
+```sh
+nix develop
+```
+
+You can have as many shells as you want, in this [flake.nix](./flake.nix), you also have
+`another_env` which includes `curl`. To open it:
+
+```sh
+nix develop .#another_env
+```
+
+## Troubleshooting
+
+### I get bash instead of my shell
+
+`nix develop` was designed for Nixpkgs stdenv, which uses bash, so that you can troubleshoot a Nix build with it. If you use a different shell, you'll want to get just the variables instead.
+
+There are 3 possible solutions:
+
+First, using [direnv](https://direnv.net/) to manage your dev environments. See [direnv-guide](https://haskell.flake.page/direnv). This is the recommended approach.
+
+Second is a simple-unreliable hack, which is adding a `shellHook` to `devShells`
+
+```nix
+devShells.default = pkgs.mkShell {
+  shellHook = ''
+    exec $SHELL
+  '';
+};
+```
+
+You might get a lot different issues, use it at your own risk.
+
+Lastly, there's `nix print-dev-env` which returns the variables - in case you're feeling adventurous, because this is far from a complete solution. See `nix print-dev-env --help`.

examples/shell-environments/flake.nix

@@ -0,0 +1,22 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, self', inputs', pkgs, system, ... }: {
+        devShells.default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ terraform wget bat nixpkgs-fmt ];
+        };
+
+        devShells.another_env = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ curl ];
+        };
+      };
+
+    };
+}

modules/devShells.nix

@@ -3,6 +3,7 @@ let
   inherit (lib)
     mkOption
     types
+    literalExpression
     ;
   inherit (flake-parts-lib)
     mkTransposedPerSystemModule
@@ -17,6 +18,13 @@ mkTransposedPerSystemModule {
       An attribute set of packages to be used as shells.
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
+    example = literalExpression ''
+      {
+        default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ wget bat cargo ];
+        };
+      }
+    '';
   };
   file = ./devShells.nix;
 }