docs: update to comments

README.md

@@ -83,7 +83,7 @@ See [the template](./template/default/flake.nix).
 
 # Examples
 
-See the folder [examples/](./examples).
+See the [examples/](./examples) directory.
 
 # Projects using flake-parts
 

examples/project-commands/README.md

@@ -8,14 +8,14 @@ This example shows how to create scripts for your project, by leveraging [missio
 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) approach (having a `scripts/` folder)
-- Using a `bin/` folder
+- 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 🚀).
+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,

examples/shell-environments/README.md

@@ -10,10 +10,10 @@ includes a diverse set of tools:
 terraform
 wget
 bat
-git
+nixpkgs-fmt
 ```
 
-You can search for more package in [nix packages](https://search.nixos.org/packages)
+You can search for more packages in [nix packages](https://search.nixos.org/packages)
 
 ## Usage
 
@@ -32,7 +32,9 @@ nix develop .#another_env
 
 ## Troubleshooting
 
-### My shell has changed
+### 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 2 possible solutions:
 
@@ -42,11 +44,12 @@ Second is a simple-unreliable hack, which is adding a `shellHook` to `devShells`
 
 ```nix
 devShells.default = pkgs.mkShell {
-    shellHook = ''
+  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

@@ -10,7 +10,7 @@
       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 git ];
+          nativeBuildInputs = with pkgs; [ terraform wget bat nixpkgs-fmt ];
         };
 
         devShells.another_env = pkgs.mkShell {

modules/devShells.nix

@@ -19,11 +19,11 @@ mkTransposedPerSystemModule {
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
     example = literalExpression ''
-    {
-      devShells.default = pkgs.mkShell {
-          nativeBuildInputs = with pkgs; [ wget bat git cargo ];
+      {
+        default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ wget bat cargo ];
         };
-    }
+      }
     '';
   };
   file = ./devShells.nix;