docs: general updates

doc/CONTRIBUTING.md

@@ -1,5 +1,8 @@
 # Pull Requests
-If making a change to core, or adding a feature, please be sure to update the
+All development is done in the `develop` branch. Only minor bug-fixes and release
+PRs should target `master`.
+
+If making a change to the template, or adding a feature, please be sure to update the
 relevant docs. Each directory contains its own README.md, which will
 automatically be pulled into the [mdbook](https://devos.divnix.com). The book is
 rendered on every change, so the docs should always be up to date.

doc/concepts/hosts.md

@@ -6,13 +6,14 @@ of these hosts, devos automatically imports every _.nix_ file inside this
 directory to the mentioned attribute set, applying the projects defaults to
 each. The only hard requirement is that the file contain a valid NixOS module.
 
-As an example, a file `hosts/system.nix` will be available via the flake
-output `nixosConfigurations.system`. You can have as many hosts as you want
-and all of them will be automatically imported based on their name.
+As an example, a file `hosts/system.nix` or `hosts/system/default.nix` will
+be available via the flake output `nixosConfigurations.system`. You can have
+as many hosts as you want and all of them will be automatically imported based
+on their name.
 
 For each host, the configuration automatically sets the `networking.hostName`
-attribute to the name of the file minus the _.nix_ extension. This is for
-convenience, since `nixos-rebuild` automatically searches for a configuration
+attribute to the folder name or name of the file minus the _.nix_ extension. This
+is for convenience, since `nixos-rebuild` automatically searches for a configuration
 matching the current systems hostname if one is not specified explicitly.
 
 You can set channels, systems, and add extra modules to each host by editing the

doc/concepts/profiles.md

@@ -8,42 +8,37 @@ separation of concerns.
 If you need guidance, a community [branch](https://github.com/divnix/devos/tree/community/profiles)
 is maintained to help get up to speed on their usage.
 
-## Constraints
-For the sake of consistency, a profile should always be defined in a
-___default.nix___ containing a [nixos module config][config].
-A profile's directory is used for quick modularization of
-[interelated bits](./profiles.md#subprofiles).
+## Creation
+Profiles are created with the `rakeLeaves` function which recursively collects
+`.nix` files from within a folder. The recursion stops at folders with a `default.nix` 
+in them. You end up with an attribute set with leaves(paths to profiles) or
+nodes(attrsets leading to more nodes or leaves).
+
+A profile is used for quick modularization of [interelated bits](./profiles.md#subprofiles).
 
 > ##### _Notes:_
 > * For _declaring_ module options, there's the [modules](../outputs/modules.md) directory.
 > * This directory takes inspiration from
 >   [upstream](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles)
 >   .
-> * Sticking to a simple [spec][spec] has refreshing advantages.
->   [hercules-ci](../integrations/hercules.md) expects all profiles to be
->   defined in a ___default.nix___, allowing them to be built automatically when
->   added. Congruently, [suites](suites.md) expect ___default.nix___ to avoid
->   having to manage their paths manually.
 
-## Subprofiles
-Profiles can also define subprofiles. They follow the same constraints outlined
-above. A good top level profile should be a high level concern, such as your
-personal development environment while the subprofiles should be more focused
-program configurations such as your text editor, and shell configs. This way,
-you can either pull in the whole development profile, or pick and choose
-individual programs.
+### Nested profiles
+Profiles can be nested in attribute sets due to the recursive nature of `rakeLeaves`.
+This can be useful to have a set of profiles created for a specific purpose. It is
+sometimes useful to have a `common` profile that has high level concerns related
+to all its sister profiles.
 
 ### Example
 
-profiles/develop/default.nix:
+profiles/develop/common.nix:
 ```nix
 {
   imports = [ ./zsh ];
   # some generic development concerns ...
 }
 ```
 
-profiles/develop/zsh/default.nix:
+profiles/develop/zsh.nix:
 ```nix
 {  ... }:
 {
@@ -52,6 +47,16 @@ profiles/develop/zsh/default.nix:
 }
 ```
 
+The examples above will end up with a profiles set like this:
+```nix
+{
+  develop = {
+    common = ./profiles/develop/common.nix;
+    zsh = ./profiles/develop/zsh.nix;
+  };
+}
+```
+
 ## Conclusion
 Profiles are the most important concept in DevOS. They allow us to keep our
 Nix expressions self contained and modular. This way we can maximize reuse

doc/concepts/suites.md

@@ -1,19 +1,13 @@
 # Suites
 Suites provide a mechanism for users to easily combine and name collecitons of
-profiles. For good examples, check out the suites defined in the community
-[branch](https://github.com/divnix/devos/blob/community/suites/default.nix).
+profiles. For good examples, check out the suites defined in the community branch.
 
-In the future, we will use suites as a mechanism for deploying various machine
-types which don't depend on hardware, such as vm's and containers.
+`suites` are a special case of an `importable` which get passed as a special
+argument (one that can be use in an `imports` line) to your hosts.
 
 They are defined with the `suites` argument in either `home` or `nixos` namespace.
 Suites should be passed as a function that take profiles as an argument.
 
-The profiles are passed based on the folder names and list passed to the relevant
-`profiles` argument. In the template's flake.nix `profiles` is set as
-`[ ./profiles ./users ]` and that corresponds to the `{ profiles, users }` argument
-pattern.
-
 ## Definition
 ```nix
 rec {

doc/concepts/users.md

@@ -23,11 +23,23 @@ your users. For a fully fleshed out example, check out the developers personal
 ```
 
 ## Home Manager
-Home Manager support follows the same principles as regular nixos configurations.
+Home Manager support follows the same principles as regular nixos configurations,
+it even gets its own namespace in your `flake.nix` as `home`.
+
 All modules defined in [user modules][modules-list] will be imported to
-Home Manager. All profiles are availabe in [suites][suites] as userProfiles.
-The `userSuites` output will be available in your Home Manager Configuration as
-the special argument, `suites`.
+Home Manager.
+User profiles can be collected in a similar fashion as system ones into a `suites`
+argument that gets passed to your home-manager users.
+
+### Example
+```nix
+{
+  home-manager.users.nixos = { suites, ... }: {
+    imports = suites.base;
+  };
+}
+```
+
 
 ## External Usage
 You can easily use the defined home-manager configurations outside of NixOS
@@ -56,5 +68,4 @@ nix build "github:divnix/devos#[email protected]
 ```
 
 [home-manager]: https://nix-community.github.io/home-manager
-[suites]: https://github.com/divnix/devos/tree/core/suites/default.nix
-[modules-list]: https://github.com/divnix/devos/tree/core/modules/module-list.nix
+[modules-list]: https://github.com/divnix/devos/tree/core/users/modules/module-list.nix