Merge pull request #304 from Pacman99/update-docs

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
+As an example, a file `hosts/system.nix` or `hosts/system/default.nix` will
-output `nixosConfigurations.system`. You can have as many hosts as you want
+be available via the flake output `nixosConfigurations.system`. You can have
-and all of them will be automatically imported based on their name.
+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
+attribute to the folder name or name of the file minus the _.nix_ extension. This
-convenience, since `nixos-rebuild` automatically searches for a configuration
+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,34 +8,29 @@ 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
+## Creation
-For the sake of consistency, a profile should always be defined in a
+Profiles are created with the `rakeLeaves` function which recursively collects
-___default.nix___ containing a [nixos module config][config].
+`.nix` files from within a folder. The recursion stops at folders with a `default.nix` 
-A profile's directory is used for quick modularization of
+in them. You end up with an attribute set with leaves(paths to profiles) or
-[interelated bits](./profiles.md#subprofiles).
+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
+### Nested profiles
-Profiles can also define subprofiles. They follow the same constraints outlined
+Profiles can be nested in attribute sets due to the recursive nature of `rakeLeaves`.
-above. A good top level profile should be a high level concern, such as your
+This can be useful to have a set of profiles created for a specific purpose. It is
-personal development environment while the subprofiles should be more focused
+sometimes useful to have a `common` profile that has high level concerns related
-program configurations such as your text editor, and shell configs. This way,
+to all its sister profiles.
-you can either pull in the whole development profile, or pick and choose
-individual programs.
 
 ### Example
 
-profiles/develop/default.nix:
+profiles/develop/common.nix:
 ```nix
 {
   imports = [ ./zsh ];
@@ -43,7 +38,7 @@ profiles/develop/default.nix:
 }
 ```
 
-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
+profiles. For good examples, check out the suites defined in the community branch.
-[branch](https://github.com/divnix/devos/blob/community/suites/default.nix).
 
-In the future, we will use suites as a mechanism for deploying various machine
+`suites` are a special case of an `importable` which get passed as a special
-types which don't depend on hardware, such as vm's and containers.
+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.
+They are defined with the `suites` argument in either the `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.
+Home Manager.
-The `userSuites` output will be available in your Home Manager Configuration as
+User profiles can be collected in a similar fashion as system ones into a `suites`
-the special argument, `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#homeConfigurations.nixos@NixOS.home.activationPac
 ```
 
 [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/users/modules/module-list.nix
-[modules-list]: https://github.com/divnix/devos/tree/core/modules/module-list.nix

doc/lib.md

@@ -1,87 +0,0 @@
-# Lib
-The lib directory mirrors the upstream concepts of [`nixpkgs:./lib`][nixpkgs-lib], 
-[`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib] and [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib],
-but also occasionally [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support].
-
-All functions defined in lib can be accessed in modules and packages as `ourlib`.
-
-For example:
-
-- you want to add a library function that depends on some packages
-and use it throughout your devos environment: place it into `./lib`
-as if you would place it into [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib].
-
-- you want to add library functions that don't depend on `pkgs`: place
-them into `./lib` as if you would place them into [`nixpkgs:./lib`][nixpkgs-lib].
-
-- need to try out a newish custom build support: place it here before
-upstreaming into [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support].
-
-- you want to reutilize certain module configuration functions or helpers:
-place them into `./lib` as if you would place them into [`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib].
-
-Once your library grows, we recoomend you start organizing them into subfolders
-analogous `nixpkgs`:
-
-| `nixpkgs`              | `devos`            |
-| ---------------------- | ------------------ |
-| `./lib`                | `./lib`            |
-| `./pkgs/pkgs-lib`      | `./lib/pkgs-lib`   |
-| `./nixos/lib`          | `./lib/nixos-lib`  |
-| `./pkgs/build-support` | `./lib/pkgs-build` |
-
-
-## Example
-lib/nixos-lib/mkCustomI3BindSym/default.nix:
-```nix
-{ pkgs, writers, ... }:
-{ name, cmd, workspace, baseKey }:
-let
-  isWorkspaceEmpty = writers.writePython3 "is-workspace-empty" {
-    libraries = [ pkgs.python3Packages.i3ipc ];
-  } (builtins.readFile ./is-workspace-empty.py);
-
-  ws = builtins.toString workspace;
-in
-''
-
-  # ${name}
-  #bindsym ${baseKey}+${ws} workspace ${ws}; exec ${cmd}
-  bindsym ${baseKey}+${ws} workspace ${ws}; exec bash -c "${isWorkspaceEmpty} && ${cmd}"
-''
-```
-
-lib/nixos-lib/mkCustomI3BindSym/is-workspace-empty.py:
-```python
-# returns 0/1 if current workspace is empty/non-empty
-
-import i3ipc
-
-i3 = i3ipc.Connection()
-tree = i3.get_tree()
-
-
-def current_workspace():
-    return tree.find_focused().workspace()
-
-
-if current_workspace().leaves():
-    print("Error current workspace is not empty")
-    exit(1)
-exit(0)
-```
-
-lib/default.nix:
-```nix
-{ nixos, pkgs, ... }:
-# ...
-{
-  # ...
-  mkCustomI3BindSym = pkgs.callPackage ./nixos-lib/mkCustomI3BindSym { };
-}
-```
-
-[nixpkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/lib
-[nixpkgs-pkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/pkgs-lib
-[nixpkgs-pkgs-build-support]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/build-support
-[nixpkgs-nixos-lib]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib

doc/mkFlakeOptions.md

@@ -40,7 +40,7 @@ nix flake
 
 *_Default_*
 ```
-"inputs.<name>"
+"self.inputs.<name>"
 ```
 
 
@@ -81,6 +81,56 @@ attribute set or path convertible to it
 
 
 
+## devshell
+Modules to include in your devos shell. the `modules` argument
+will be exported under the `devshellModules` output
+
+
+*_Type_*:
+submodule
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## devshell.externalModules
+modules to include that won't be exported
+meant importing modules from external flakes
+
+
+*_Type_*:
+list of valid module or path convertible to its or anything convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## devshell.modules
+modules to include in all hosts and export to devshellModules output
+
+
+*_Type_*:
+list of path to a modules or anything convertible to it or path convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
 ## home
 hosts, modules, suites, and profiles for home-manager
 
@@ -103,7 +153,7 @@ meant importing modules from external flakes
 
 
 *_Type_*:
-list of valid module or path convertible to its
+list of valid module or path convertible to its or anything convertible to it
 
 
 *_Default_*
@@ -114,6 +164,34 @@ list of valid module or path convertible to its
 
 
 
+## home.importables
+Packages of paths to be passed to modules as `specialArgs`.
+
+
+*_Type_*:
+attribute set
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## home.importables.suites
+collections of profiles
+
+
+*_Type_*:
+attribute set of list of paths or anything convertible to its
+
+
+
+
+
+
 ## home.modules
 modules to include in all hosts and export to homeModules output
 
@@ -131,10 +209,17 @@ list of path to a modules or anything convertible to it or path convertible to i
 
 
 ## home.profiles
-profile folders that can be collected into suites
+WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-the name of the argument passed to suites is based
+both with the importables option. `rakeLeaves` can be used to create profiles and
-on the folder name.
+by passing a module or `rec` set to `importables`, suites can access profiles.
-[ ./profiles ] => { profiles }:
+Example:
+```
+importables = rec {
+  profiles = digga.lib.importers.rakeLeaves ./profiles;
+  suites = with profiles; { };
+}
+```
+See https://github.com/divnix/digga/pull/30 for more details
 
 
 *_Type_*:
@@ -150,31 +235,23 @@ list of paths
 
 
 ## home.suites
-Function that takes profiles and returns suites for this config system
+WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-These can be accessed through the 'suites' special argument.
+both with the importables option. `rakeLeaves` can be used to create profiles and
+by passing a module or `rec` set to `importables`, suites can access profiles.
+Example:
+```
+importables = rec {
+  profiles = digga.lib.importers.rakeLeaves ./profiles;
+  suites = with profiles; { };
+}
+```
+See https://github.com/divnix/digga/pull/30 for more details
 
 
 *_Type_*:
 function that evaluates to a(n) attrs or path convertible to it
 
 
-*_Default_*
-```
-"<function>"
-```
-
-
-
-
-## inputs
-inputs for this flake
-used to set channel defaults and create registry
-
-
-*_Type_*:
-attribute set of nix flakes
-
-
 
 
 
@@ -236,7 +313,7 @@ meant importing modules from external flakes
 
 
 *_Type_*:
-list of valid module or path convertible to its
+list of valid module or path convertible to its or anything convertible to it
 
 
 *_Default_*
@@ -343,11 +420,46 @@ null
 
 
 
+## nixos.importables
+Packages of paths to be passed to modules as `specialArgs`.
+
+
+*_Type_*:
+attribute set
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## nixos.importables.suites
+collections of profiles
+
+
+*_Type_*:
+attribute set of list of paths or anything convertible to its
+
+
+
+
+
+
 ## nixos.profiles
-profile folders that can be collected into suites
+WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-the name of the argument passed to suites is based
+both with the importables option. `rakeLeaves` can be used to create profiles and
-on the folder name.
+by passing a module or `rec` set to `importables`, suites can access profiles.
-[ ./profiles ] => { profiles }:
+Example:
+```
+importables = rec {
+  profiles = digga.lib.importers.rakeLeaves ./profiles;
+  suites = with profiles; { };
+}
+```
+See https://github.com/divnix/digga/pull/30 for more details
 
 
 *_Type_*:
@@ -363,17 +475,39 @@ list of paths
 
 
 ## nixos.suites
-Function that takes profiles and returns suites for this config system
+WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-These can be accessed through the 'suites' special argument.
+both with the importables option. `rakeLeaves` can be used to create profiles and
+by passing a module or `rec` set to `importables`, suites can access profiles.
+Example:
+```
+importables = rec {
+  profiles = digga.lib.importers.rakeLeaves ./profiles;
+  suites = with profiles; { };
+}
+```
+See https://github.com/divnix/digga/pull/30 for more details
 
 
 *_Type_*:
 function that evaluates to a(n) attrs or path convertible to it
 
 
+
+
+
+
+## outputsBuilder
+builder for flake system-spaced outputs
+The builder gets passed an attrset of all channels
+
+
+*_Type_*:
+function that evaluates to a(n) attrs
+
+
 *_Default_*
 ```
-"<function>"
+"channels: { }"
 ```
 
 

doc/outputs/pkgs.md

@@ -7,8 +7,7 @@ The only minor difference is that, instead of adding the `callPackage` call to
 `all-packages.nix`, you just add it the the _default.nix_ in this directory,
 which is defined as a simple overlay.
 
-This overlay is set as the default `overlay` output attribute for the flake.
+All the packages are exported via `packages.<system>.<pkg-name>`, for all
-And all the packages are exported via `packages.<system>.<pkg-name>`, for all
 the supported systems listed in the package's `meta.platforms` attribute.
 
 And, as usual, every package in the overlay is also available to any NixOS

doc/tests.md

@@ -5,22 +5,19 @@ NixOS offers some incredibly powerful tools to write tests for your
 configuration, and, optionally, run them in
 [CI](./integrations/hercules.md).
 
-## Lib Tests
-You can easily write tests for your own library functions in the
-lib/___tests/lib.nix___ file and they will be run on every `nix flake check` or
-during a CI run.
-
 ## Unit Tests
-Unit tests are can be created from regular derivations, and they can do
+Unit tests can be created from regular derivations, and they can do
 almost anything you can imagine. By convention, it is best to test your
 packages during their [check phase][check]. All packages and their tests will
 be built during CI.
 
 ## Integration Tests
+All your profiles defined in suites will be tested in a NixOS VM.
+
 You can write integration tests for one or more NixOS VMs that can,
 optionally, be networked together, and yes, it's as awesome as it sounds!
 
-Be sure to use the `mkTest` function, in the [___tests/default.nix___][default]
+Be sure to use the `mkTest` function from digga, `digga.lib.pkgs-lib.mkTest`
 which wraps the official [testing-python][testing-python] function to ensure
 that the system is setup exactly as it is for a bare DevOS system. There are
 already great resources for learning how to use these tests effectively,