doc: move all docs under doc

.gitignore

@@ -2,4 +2,4 @@ result
 up
 hosts/up-*
 .direnv
-book
+doc/index.html

README.md

@@ -55,10 +55,10 @@ There are two branches from which to choose: [core][core] and
 several ready-made profiles for discretionary use.
 
 Every package and NixOS profile declared in community is uploaded to
-[cachix](./cachix), so everything provided is available without building
-anything. This is especially useful for the packages that are
-[overridden](./overrides) from master, as without the cache, rebuilds are
-quite frequent.
+[cachix](./integrations/cachix.md), so everything provided is available
+without building anything. This is especially useful for the packages that are
+[overridden](./concepts/overrides.md) from master, as without the cache,
+rebuilds are quite frequent.
 
 ## Inspiration & Art
 - [hlissner/dotfiles][dotfiles]

SUMMARY.md

@@ -1,32 +0,0 @@
-# Summary
-
-- [Introduction](./README.md)
-- [Quick Start](./doc/start/index.md)
-  - [ISO](./doc/start/iso.md)
-  - [Bootstrapping](./doc/start/bootstrapping.md)
-  - [From NixOS](./doc/start/from-nixos.md)
-- [Layout](./doc/layout.md)
-  - [Cachix](./cachix/README.md)
-  - [Extern](./extern/README.md)
-  - [Hosts](./hosts/README.md)
-  - [Lib](./lib/README.md)
-  - [Modules](./modules/README.md)
-  - [Overlays](./overlays/README.md)
-  - [Overrides](./overrides/README.md)
-  - [Packages](./pkgs/README.md)
-  - [Profiles](./profiles/README.md)
-  - [Secrets](./secrets/README.md)
-  - [Suites](./suites/README.md)
-  - [Tests](./tests/README.md)
-  - [Users](./users/README.md)
-- [flk](./doc/flk/index.md)
-  - [up](./doc/flk/up.md)
-  - [update](./doc/flk/update.md)
-  - [get](./doc/flk/get.md)
-  - [iso](./doc/flk/iso.md)
-  - [install](./doc/flk/install.md)
-  - [home](./doc/flk/home.md)
-- [Integrations](doc/integrations/index.md)
-  - [Deploy RS](./doc/integrations/deploy.md)
-  - [Hercules CI](./doc/integrations/hercules.md)
-- [Contributing](./doc/README.md)

doc/SUMMARY.md

@@ -0,0 +1,34 @@
+# Summary
+
+- [Introduction](../README.md)
+- [Quick Start](./start/index.md)
+  - [ISO](./start/iso.md)
+  - [Bootstrapping](./start/bootstrapping.md)
+  - [From NixOS](./start/from-nixos.md)
+- [Key Concepts](./concepts/index.md)
+  - [Extern](./concepts/extern.md)
+  - [Hosts](./concepts/hosts.md)
+  - [Overrides](./concepts/overrides.md)
+  - [Profiles](./concepts/profiles.md)
+  - [Suites](./concepts/suites.md)
+  - [Users](./concepts/users.md)
+- [Outputs](./outputs/index.md)
+  - [Modules](./outputs/modules.md)
+  - [Overlays](./outputs/overlays.md)
+  - [Packages](./outputs/pkgs.md)
+- [Concerns]()
+  - [Lib](./lib.md)
+  - [Secrets](./secrets.md)
+  - [Tests](./tests.md)
+- [Helper Script – `flk`](./flk/index.md)
+  - [up](./flk/up.md)
+  - [update](./flk/update.md)
+  - [get](./flk/get.md)
+  - [iso](./flk/iso.md)
+  - [install](./flk/install.md)
+  - [home](./flk/home.md)
+- [Integrations](./integrations/index.md)
+  - [Cachix](./integrations/cachix.md)
+  - [Deploy RS](./integrations/deploy.md)
+  - [Hercules CI](./integrations/hercules.md)
+- [Contributing](./CONTRIBUTING.md)

doc/concepts/hosts.md

@@ -17,16 +17,16 @@ matching the current systems hostname if one is not specified explicitly.
 
 It is recommended that the host modules only contain configuration information
 specific to a particular piece of hardware. Anything reusable across machines
-is best saved for [profile modules](../profiles).
+is best saved for [profile modules](./profiles.md).
 
-This is a good place to import sets of profiles, called [suites](../suites),
+This is a good place to import sets of profiles, called [suites](./suites.md),
 that you intend to use on your machine.
 
 Additionally, this is the perfect place to import anything you might need from
 the [nixos-hardware][nixos-hardware] repository.
 
 > ##### _Note:_
-> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux". 
+> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux".
 > Keep in mind that not all packages are available for all architectures.
 
 ## Example

doc/concepts/index.md

@@ -0,0 +1,4 @@
+# Key Concepts
+
+There are few idioms unique to DevOS. This section is dedicated to helping you
+understand them.

doc/concepts/profiles.md

@@ -12,17 +12,17 @@ is maintained to help get up to speed on their usage.
 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](./#subprofiles).
+[interelated bits](./profiles.md#subprofiles).
 
 > ##### _Notes:_
-> * For _declaring_ module options, there's the [modules](../modules) directory.
+> * 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](../doc/integrations/hercules.md) expects all profiles to be
+>   [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) expect ___default.nix___ to avoid
+>   added. Congruently, [suites](suites.md) expect ___default.nix___ to avoid
 >   having to manage their paths manually.
 
 ## Subprofiles
@@ -56,7 +56,7 @@ profiles/develop/zsh/default.nix:
 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
 across hosts while minimizing boilerplate. Remember, anything machine
-specific belongs in your [host](../hosts) files instead.
+specific belongs in your [host](hosts.md) files instead.
 
 [definition]: https://nixos.org/manual/nixos/stable/index.html#sec-option-definitions
 [declaration]: https://nixos.org/manual/nixos/stable/index.html#sec-option-declarations

doc/concepts/users.md

@@ -1,6 +1,6 @@
 # Users
 
-Users are a special case of [profiles](../profiles) that define system
+Users are a special case of [profiles](profiles.md) that define system
 users and [home-manager][home-manager] configurations. For your convenience,
 home manager is wired in by default so all you have to worry about is declaring
 your users. For a fully fleshed out example, check out the developers personal
@@ -24,14 +24,14 @@ 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.
-All modules defined in [user modules](./modules/module-list.nix) will be imported to 
-Home Manager. All profiles are availabe in [suites](../suites/default.nix) as userProfiles.
+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`.
 
 ## External Usage
 You can easily use the defined home-manager configurations outside of NixOS
-using the `homeConfigurations` flake output. The [flk](../doc/flk) helper 
+using the `homeConfigurations` flake output. The [flk](../flk/index.md) helper
 script makes this even easier.
 
 This is great for keeping your environment consistent across Unix systems,
@@ -56,3 +56,5 @@ 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/modules/module-list.nix

doc/flk/home.md

@@ -4,5 +4,5 @@ NixOS, providing an awesome mechanism for keeping your environments
 synchronized, even when using other systems.
 
 ## Usage
-The [users](../../users/index.md#external-usage) page contains a good usage
+The [users](../concepts/users.md#external-usage) page contains a good usage
 example.

doc/flk/update.md

@@ -11,8 +11,8 @@ contains a flake.nix, with an optional arguement to update only a specific
 input in the subflake.
 
 For example, you can update any
-[package sources](../../pkgs#automatic-source-updates) you may have declared
-in _pkgs/flake.nix_:
+[package sources](../outputs/pkgs.md#automatic-source-updates) you may have
+declared in _pkgs/flake.nix_:
 ```sh
 flk update pkgs
 ```

doc/integrations/deploy.md

@@ -4,7 +4,7 @@ chosen for devos after the author experienced some frustrations with the
 stateful nature of nixops' db. It was also designed from scratch to support
 flake based deployments, and so is an excellent tool for the job.
 
-By default, all the [hosts](../../hosts) are also available as deploy-rs nodes,
+By default, all the [hosts](../concepts/hosts.md) are also available as deploy-rs nodes,
 configured with the hostname set to `networking.hostName`; overridable via
 the command line.
 

doc/layout.md

@@ -1,4 +0,0 @@
-# Layout
-Each of the following sections is a directory in the root of the project
-serving a singular purpose. Select a chapter to read more about its purpose
-and usage.

doc/outputs/index.md

@@ -0,0 +1,3 @@
+# Layout
+Each of the following sections is a directory whose contents are output to the
+outside world via the flake's outputs. Check each chapter for details.

doc/outputs/modules.md

@@ -4,13 +4,13 @@ The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules]
 nixpkgs proper once your module is sufficiently stable.
 
 All modules linked in _module-list.nix_ are automatically exported via
-`nixosModules.<file-basename>`, and imported into all [hosts](../hosts).
+`nixosModules.<file-basename>`, and imported into all [hosts](../concepts/hosts.md).
 
 
 > ##### _Note:_
 > This is reserved for declaring brand new module options. If you just want to
 > declare a coherent configuration of already existing and related NixOS options
-> , use [profiles](../profiles) instead.
+> , use [profiles](../concepts/profiles.md) instead.
 
 ## Semantics
 In case you've never written a module for nixpkgs before, here is a brief

doc/outputs/overlays.md

@@ -3,7 +3,7 @@ Writing overlays is a common occurence when using a NixOS system. Therefore,
 we want to keep the process as simple and straightforward as possible.
 
 Any _.nix_ files declared in this directory will be assumed to be a valid
-overlay, and will be automatically imported into all [hosts](../hosts), and
+overlay, and will be automatically imported into all [hosts](../concepts/hosts.md), and
 exported via `overlays.<file-basename>` _as well as_
 `packages.<system>.<pkgName>` (for valid systems), so all you have to do is
 write it.

doc/outputs/pkgs.md

@@ -1,5 +1,5 @@
 # Packages
-Similar to [modules](../modules), the pkgs directory mirrors the upstream
+Similar to [modules](./modules.md), the pkgs directory mirrors the upstream
 [nixpkgs/pkgs][pkgs], and for the same reason; if you ever want to upstream
 your package, it's as simple as dropping it into the nixpkgs/pkgs directory.
 
@@ -12,18 +12,17 @@ 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
-[host](../hosts).
+[host](../concepts/hosts.md).
 
 ## Automatic Source Updates
 There is the added, but optional, convenience of declaring your sources in
 _pkgs/flake.nix_ as an input. You can then access them from the `srcs` package.
 This allows updates to be managed automatically by simply
-[updating](../doc/flk/update.md#updating-package-sources) the lock file. No
+[updating](../flk/update.md#updating-package-sources) the lock file. No
 more manually entering sha256 hashes!
 
 As an added bonus, version strings are also generated automatically from either
-the flake ref, or the date and git revision of the source. For examples,
-definitely checkout the [community branch](../#community-profiles).
+the flake ref, or the date and git revision of the source.
 
 ## Example
 pkgs/development/libraries/libinih/default.nix:

doc/start/bootstrapping.md

@@ -1,9 +1,9 @@
 # Bootstrapping
 
-This will help you boostrap a bare host with the help of the 
-[bespoke iso](./iso) live installer.
+This will help you boostrap a bare host with the help of the
+[bespoke iso](./iso.md) live installer.
 
-_Note: nothing prevents you from remotely executing the boostrapping 
+_Note: nothing prevents you from remotely executing the boostrapping
 process. See below._
 
 Once your target host has booted into the live iso, you need to partion
@@ -14,7 +14,7 @@ and format your disk according to the [official manual][manual].
 Then properly mount the formatted partitions at `/mnt`, so that you can
 install your system to those new partitions.
 
-Mount `nixos` partition to `/mnt` and — for UEFI — `boot` 
+Mount `nixos` partition to `/mnt` and — for UEFI — `boot`
 partition to `/mnt/boot`:
 
 ```console
@@ -25,7 +25,7 @@ $ swapon /dev/$your_swap_partition
 
 ## Install
 
-Install using the `flk` wrapper baked into the iso off of a copy of devos 
+Install using the `flk` wrapper baked into the iso off of a copy of devos
 from the time the iso was built:
 
 ```console
@@ -41,7 +41,7 @@ $ flk install NixOS --impure # use same host as above
 ### Remote access to the live installer
 
 The iso live installer comes preconfigured with a network configuration
-which announces it's hostname via [MulticastDNS][mDNS] as `hostname.local`, 
+which announces it's hostname via [MulticastDNS][mDNS] as `hostname.local`,
 that is `NixOS.local` in the [iso example](./iso).
 
 In the rare case that [MulticastDNS][mDNS] is not availabe or turned off
@@ -50,7 +50,7 @@ in your network, there is a static link-local IPv6 address configured to
 `n=14 i=9 x=24; 47 = n+i+x`).
 
 Provided that you have added your public key to the authorized keys of the
-`root` user _(hint: [`deploy-rs`](../integrations/deploy) needs passwordless
+`root` user _(hint: [`deploy-rs`](../integrations/deploy.md) needs passwordless
 sudo access)_:
 
 ```nix
@@ -62,7 +62,7 @@ sudo access)_:
 }
 ```
 
-You can then ssh into the live installer through one of the 
+You can then ssh into the live installer through one of the
 following options:
 
 ```console
@@ -73,7 +73,7 @@ ssh root@fe80::47%eno1  # where eno1 is your network interface on which you are
 
 _Note: the [static link-local IPv6 address][staticLLA] and [MulticastDNS][mDNS] is only
 configured on the live installer. If you wish to enable [MulticastDNS][mDNS]
-for your environment, you ought to configure that in a regular [profile](../../profiles)._
+for your environment, you ought to configure that in a regular [profile](../concepts/profiles.md)._
 
 ### EUI-64 LLA & Host Identity
 
@@ -88,7 +88,7 @@ specific address over [NDP][NDP] for example with:
 ip -6 neigh show # also shows fe80::47
 ```
 
-***This LLA is stable for the host, unless you need to swap that particular network card.*** 
+***This LLA is stable for the host, unless you need to swap that particular network card.***
 Under this reservation, though, you may use this EUI-64 to wire up a specific
 (cryptographic) host identity.
 

doc/start/from-nixos.md

@@ -15,8 +15,8 @@ your region. Keep in mind that `networking.hostName` with be automatically
 set to the filename of your hosts file, so `hosts/my-host.nix` will have the
 hostname `my-host`.
 
-Now might be a good time to read the docs on [suites](../../suites) and
-[profiles](../../profiles) and add or create any that you need.
+Now might be a good time to read the docs on [suites](../concepts/suites.md) and
+[profiles](../concepts/profiles.md) and add or create any that you need.
 
 > ##### _Note:_
 > While the `up` sub-command is provided as a convenience to quickly set up and

doc/start/index.md

@@ -22,7 +22,7 @@ This will place you in a new folder named `flk` with git initialized, and a
 nix-shell that provides all the dependencies, including the unstable nix
 version required.
 
-In addition, the [binary cache](../../cachix) is added for faster deployment.
+In addition, the [binary cache](../integrations/cachix.md) is added for faster deployment.
 
 > ##### _Notes:_
 > - You can change `core` to [`community`](../../index.md#community-profiles)

doc/tests.md

@@ -0,0 +1,36 @@
+# Testing
+
+Testing is always an important aspect of any software development project, and
+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
+___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
+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
+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]
+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,
+including the official [docs][test-doc], a fantastic [blog post][test-blog],
+and the examples in [nixpkgs][nixos-tests].
+
+[test-doc]: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
+[test-blog]: https://www.haskellforall.com/2020/11/how-to-use-nixos-for-lightweight.html
+[default]: https://github.com/divnix/devos/tree/core/tests/default.nix
+[run-test]: https://github.com/NixOS/nixpkgs/blob/6571462647d7316aff8b8597ecdf5922547bf365/lib/debug.nix#L154-L166
+[nixos-tests]: https://github.com/NixOS/nixpkgs/tree/master/nixos/tests
+[testing-python]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing-python.nix
+[check]: https://nixos.org/manual/nixpkgs/stable/#ssec-check-phase