doc: finish flk reference

README.md

@@ -1,233 +1,45 @@
-> Since flakes are still quite new, I've listed some learning resources
-> [below](#resources).
-
 # Introduction
-Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
+Nixflk is a template which grants a simple way to use, deploy and manage
-mechanism. Its aim is to provide a generic repository which neatly separates
+[NixOS][nixos] systems for personal and productive use. It does this by
-concerns and allows one to get up and running with NixOS faster than ever, while
+providing a sane repository structure, integrating several popular projects
-keeping your code clean and organized.
+like [home-manager][home-manager], setting clear guidelines, offering useful
+conveniences, and eliminating boilerplate so you can focus on deploying your
+systems.
 
-Some key advantages include:
+## Getting Started
-* A single home for all your Nix expressions, easily sharable and portable!
+Check out the [guide](https://flk.nrdxp.dev/doc/start) to get up and running.
-* Skip the boilerplate, simply use the included [nix-shell](./shell.nix) or
-  [direnv][direnv] profile and get up and running with flakes right away.
-* Thanks to flakes, the entire system is more [deterministic](./flake.lock).
-* Systems defined under [hosts](./hosts) are automatically imported into
-  `nixosConfigurations`, ready to deploy.
-* [Profiles](./profiles/list.nix) are a simple mechanism for using portable
-  code across machines.
-* Defined [packages](./pkgs/default.nix) and
-  [modules](./modules/list.nix), are automatically wired and available from
-  anywhere. They are _also_ sharable via their respective flake outputs.
-* Easily [override](./unstable/default.nix) packages from different nixpkgs
-  versions.
-* Keep [user](./users) configuration isolated and easily reusable by taking
-  advantage of [user profiles](./users/profiles) and [home-manager][home-manager].
-* [Overlay](./overlays) files are automatically available and sharable.
-* Automatic [NUR][nur] support.
 
-For a more detailed explanation of the code structure, check out the
+## Motivation
-[docs](./DOC.md).
+NixOS provides an amazing abstraction to manage our computers, but that new
+power can sometimes bring feelings of overwhelm and confusion. Having a turing
+complete programming language can add an unlimited potential for complexity if
+we do it wrong. Instead, we should have a community consensus on how to manage
+a NixOS system — consider this a first attempt.
 
-### ⚠ Advisory
+___The future is declarative! 🎉___
-Flakes are still new, so not everything works yet. However, it has been to
-merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
-project should be considered _experimental_, until flakes become the default.
 
-Also, flakes are meant to deprecate nix-channels. It's recommended not to
+## Community Profiles
-install any. If your really want them, they should work if you hook them into
+There are two branches from which to choose: [core][core] and
-`NIX_PATH`.
+[community][community]. The community branch builds on core and includes
+several ready-made profiles for discretionary use.
 
-# Setup
+Every package and NixOS profile declared in community is uploaded to
-There are a few ways to get up and running. You can fork this repo or use it as
+[cachix](./cachix), so everything provided is available without building
-a template. There is a [community][community] branch with a bunch of useful
+anything. This is especially useful for the packages that are
-profiles, modules, overlays, etc, already configured for you to use. Please
+[overridden](./overrides) from master, as without the cache, rebuilds are
-consider adding your own expressions there if you feel they would be helpful
+quite frequent.
-for others.
-
-The only hard requirement is nix itself. The `shell.nix` will pull in
-everything else.
-
-## Flake Templates
-If you already have [nix-command][nix-command] setup you can:
-```sh
-# for the core template with no profiles
-nix flake new -t "github:nrdxp/nixflk" flk
-
-# for the community template
-nix flake new -t "github:nrdxp/nixflk/community" flk
-```
-
-## Nix Only
-Once you have this repo, you'll want to __move or symlink__ it to `/etc/nixos`
-for ease of use. Once inside:
-```sh
-# probably want to use a separate branch for you config
-git checkout -b my-branch
-
-# This will setup nix-command and pull in the needed tools
-nix-shell # or `direnv allow` if you prefer
-
-# use nixos-generate-config to generate a basic config for your system
-# edit hosts/up-$(hostname).nix to modify.
-flk up
-
-# The following should work fine for EFI systems.
-# boot.loader.systemd-boot.enable = true;
-# boot.loader.efi.canTouchEfiVariables = true;
-
-# Set your locale
-$EDITOR local/locale.nix
-
-# install NixOS to bare metal
-flk install yourConfig # deploys hosts/yourConfig.nix
-
-# if you already have NixOS and just want to deploy your new setup
-flk yourConfig switch
-```
-
-### Note on `flk up`:
-While the `up` sub-command is provided as a convenience to quickly set up and
-install a "fresh" NixOS system on current hardware, committing these files is
-discouraged.
-
-They are placed in the git staging area automatically because they would be
-invisible to the flake otherwise, but it is best to move what you need from
-them directly into your hosts file and commit that instead.
-
-# Sharing
-One of the great benefits of flakes is the ability to easily share your user
-defined packages, modules and other nix expressions without having to merge
-anything upstream. In that spirit, everything defined in this flake is usable
-from other flakes. So even if you don't want to use this project as a template,
-you can still pull in any useful modules, packages or profiles defined here.
-
-From the command line:
-```sh
-# to see what this flake exports
-nix flake show "github:nrdxp/nixflk"
-
-# run an app
-nix run "github:nrdxp/nixflk#someApp"
-
-# start a dev shell for a given derivation
-nix develop "github:nrdxp/nixflk#somePackage"
-
-# a nix shell with the package in scope
-nix shell "github:nrdxp/nixflk#somePackage"
-```
-
-From within a flake:
-```nix
-{
-  inputs.nixflk.url = "github:nrdxp/nixflk";
-
-  outputs = { self, nixpkgs, nixflk, ... }:
-  {
-    nixosConfigurations.example = nixpkgs.lib.nixosSystem {
-      # ...
-        modules = [
-        nixflk.nixosModules.someModule
-        ({
-          nixpkgs.overlays = [ nixflk.overlay nixflk.overlays.someOverlay ];
-        })
-        # ...
-      ];
-    };
-  };
-}
-```
-
-## Home Manager Integration
-The home-manager nixos module is available for each host. It is meant
-to be used in the user profiles, you can find an example in the nixos user profile
-
-The home-manager configuration for each user in each system is available in the
-outputs as homeConfigurations and the activation packages in hmActivationPackages.
-
-This allows you to just build the home-manager environment without the rest of the
-system configuration. The feature is useful on systems without nixos or root access.
-
-Lets say you want to activate the home configuration for the user `nixos` in the
-host `NixOS`.
-
-With the flk script:
-```sh
-# You can build it using
-flk home NixOS nixos
-# and activate with
-./result/activate
-
-# Or do both like this
-flk home NixOS nixos switch
-```
-
-## Build an ISO
-
-You can make an ISO out of any config:
-```sh
-flk iso yourConfig # build an iso for hosts/yourConfig.nix
-```
-
-## Hardware Specific Profile for a Single Host
-
-Find out the fitting
-[nixos-hardware profile](https://github.com/NixOS/nixos-hardware#list-of-profiles)
-for the hardware of your host, then find the corresponding modules in the
-[flake](https://github.com/NixOS/nixos-hardware/blob/master/flake.nix) and add
-it to the configuration. For example for a Dell XPS 13 9370 the host
-configuration would contain:
-```nix
-{ hardware, ... }:
-{
-  imports = [ hardware.dell-xps-13-9370 ... ];
-  ...
-}
-```
-
-## Use a Package from NUR
-
-NUR is wired in from the start. For safety, nothing is added from it by default,
-but you can easily pull packages from inside your configuration like so:
-```nix
-{ pkgs, ... }:
-{
-  environment.systemPackages = with pkgs; [ nur.repos.<owner>.<package> ];
-}
-```
-# Resources
-
-## Links
-* [Example Repo](https://github.com/colemickens/nixos-flake-example)
-* [Tweag.io _Flakes_ Blog Series](https://www.tweag.io/blog/2020-05-25-flakes)
-* [NixOS _Flakes_ Wiki](https://nixos.wiki/wiki/Flakes)
-* [Zimbatm's _Flakes_ Blog](https://zimbatm.com/NixFlakes)
-* [Original RFC](https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md)
-
-## Flake Talk:
-[![Flake talk at NixConf][thumb]][video]
 
+> #### ⚠ Advisory ⚠
+> Nixflk leverages the [flakes][flakes] feature available via an _experimental_
+> branch of [nix][nix]. Until nix 3.0 is released, this project should be
+> considered unstable.
 
 # License
+Nixflk is licensed under the [MIT License](https://mit-license.org).
 
-This software is licensed under the [MIT License](COPYING).
+[nix]: https://nixos.org/manual/nix/stable
-
+[nixos]: https://nixos.org/manual/nixos/stable
-Note: MIT license does not apply to the packages built by this configuration,
+[home-manager]: https://nix-community.github.io/home-manager
-merely to the files in this repository (the Nix expressions, build
+[flakes]: https://nixos.wiki/wiki/Flakes
-scripts, NixOS modules, etc.). It also might not apply to patches
+[core]: https://github.com/nrdxp/nixflk
-included here, which may be derivative works of the packages to
-which they apply. The aforementioned artifacts are all covered by the
-licenses of the respective packages.
-
 [community]: https://github.com/nrdxp/nixflk/tree/community
-[direnv]: https://direnv.net
-[home-manager]: https://github.com/nix-community/home-manager
-[nix-command]: https://nixos.wiki/wiki/Nix_command
-[nixFlakes]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/package-management/nix/default.nix#L211
-[NixOS]: https://nixos.org
-[nixpkgs]: https://github.com/NixOS/nixpkgs
-[nur]: https://github.com/nix-community/NUR
-[wiki]: https://nixos.wiki/wiki/Flakes
-[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg
-[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
-[nur]: https://github.com/nix-community/NUR

SUMMARY.md

@@ -1,6 +1,6 @@
 # Summary
 
-- [Introduction](./doc/introduction.md)
+- [Introduction](./README.md)
 - [Quick Start](./doc/start/index.md)
   - [ISO](./doc/start/iso.md)
   - [From NixOS](./doc/start/from-nixos.md)
@@ -16,4 +16,11 @@
   - [Secrets](./secrets/README.md)
   - [Suites](./suites/README.md)
   - [Users](./users/README.md)
-- [flk command](./doc/flk/index.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)
+- [Contributing](./doc/README.md)

doc/CONTRIBUTING.md

@@ -0,0 +1 @@
+# Contributing

doc/README.md

@@ -0,0 +1,26 @@
+# Pull Requests
+If making a change to core, 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://flk.nrdxp.dev). The book is
+rendered on every change, so the docs should always be up to date.
+
+
+## Community PRs
+While much of your work in this template may be idiosyncratic in nature. Anything
+that might be generally useful to the broader NixOS community can be synced to
+the `community` branch to provide a host of useful NixOS configurations available
+"out of the box".
+
+# Style
+If you wish to contribute please follow these guidelines:
+
+* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
+  includes a pre-commit hook that does this for you.
+
+* The commit message follows the same semantics as [nixpkgs][nixpkgs].
+  * You can use a `#` symbol to specify ambiguities. For example,
+  `develop#zsh: <rest of commit message>` would tell me that your updating the
+  `zsh` subprofile living under the `develop` profile.
+
+[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
+[nixpkgs]: https://github.com/NixOS/nixpkgs

doc/flk/get.md

@@ -0,0 +1,10 @@
+# get
+The `get` subcommand is useful for getting a bare copy of nixflk without the
+git history. You can pull either the core or community branches.
+
+## Usage
+```sh
+flk get BRANCH DEST-DIR
+```
+
+If DEST-DIR is ommitted, it defaults to _./flk_.

doc/flk/home.md

@@ -0,0 +1,8 @@
+# home
+The `home` subcommand is for using your home-manager configurations outside of
+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
+example.

doc/flk/index.md

@@ -1 +1,20 @@
 # flk command
+The devshell for the project incudes a convenient script for managing your
+system called `flk`. Each of the following chapters is a reference for one of
+its subcommands.
+
+## Rebuild
+Without any of the subcommands, `flk` acts as a convenient shortcut for
+`nixos-rebuild`:
+```sh
+flk NixOS build
+```
+
+Will build _hosts/NixOS.nix_. You can change out `build` for `switch`, `test`,
+etc. Any additional arguments are passed through to the call to
+`nixos-rebuild`.
+
+## Usage
+```sh
+flk help
+```

doc/flk/install.md

@@ -0,0 +1,12 @@
+# install
+The `install` subcommand is a simple convenience for `nixos-install`, similar
+to the shortcut for `nixos-rebuild`, all additional arguments are passed
+through.
+
+## Example
+```sh
+flk install NixOS
+```
+
+This will install _hosts/NixOS.nix_ to /mnt. You can override this directory
+using standard `nixos-install` args.

doc/flk/iso.md

@@ -0,0 +1 @@
+../start/iso.md

doc/flk/up.md

@@ -0,0 +1,4 @@
+# up
+The `up` subcommand is a simple shortcut for `nixos-generate-config` that is
+compatible with nixflk. There is a short explanation in the the getting started
+[guide](../start/from-nixos.md#generate-configuration).

doc/flk/update.md

@@ -0,0 +1,6 @@
+# update
+The `update` subcommand is a simple alias for:
+```sh
+nix flake update --recreate-lock-file --commit-lock-file
+```
+As it sounds, this will update your lock file, and commit it.

doc/introduction.md

@@ -1,33 +0,0 @@
-# Introduction
-Nixflk is a template which grants a simple way to use, deploy and manage
-[NixOS][nixos] systems for personal and productive use. It does this by
-providing a sane repository structure, integrating several popular projects
-like [home-manager][home-manager], setting clear guidelines, offering useful
-conveniences, and eliminating boilerplate so you can focus on deploying your
-systems.
-
-## Community Profiles
-There are two branches from which to choose: [core][core] and
-[community][community]. The community branch builds on core and includes
-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.
-
-### ⚠ Advisory
-Nixflk leverages the [flakes][flakes] feature available via an _experimental_
-branch of [nix][nix]. Until nix 3.0 is released, this project should be
-considered unstable.
-
-# License
-Nixflk is licensed under the [MIT License](https://mit-license.org).
-
-[nix]: https://nixos.org/manual/nix/stable
-[nixos]: https://nixos.org/manual/nixos/stable
-[home-manager]: https://nix-community.github.io/home-manager
-[flakes]: https://nixos.wiki/wiki/Flakes
-[core]: https://github.com/nrdxp/nixflk
-[community]: https://github.com/nrdxp/nixflk/tree/community

doc/start/index.md

@@ -25,7 +25,7 @@ version required.
 In addition, the [binary cache](../../cachix) is added for faster deployment.
 
 > ##### _Notes:_
-> - You can change `core` to [`community`](../introduction.md#community-profiles)
+> - You can change `core` to [`community`](../../index.md#community-profiles)
 >   in the call to `flk get`
 > - Flakes ignore files that have not been added to git, so be sure to stage new
 >   files before building the system.

hosts/README.md

@@ -27,7 +27,7 @@ the [nixos-hardware][nixos-hardware] repository.
 
 ## Example
 
-`hosts/librem.nix`:
+hosts/librem.nix:
 ```nix
 { suites, hardware, ... }:
 {