Merge #435

435: Merge devos docs and README into top-level r=blaggacao a=Pacman99

I think some more work needs to be done to get the docs to flow better, but for now this puts everything in one place so we have a starting point to improve everything.

The new readme is a mix of what I thought were the best parts of both readmes.

Co-authored-by: Parthiv Seetharaman <pachum99@myrdd.info>

README.md

@@ -14,10 +14,27 @@ environment within a single [nix flakes][flakes] repository:
 
 This library is based on [flake-utils-plus][].
 
+# Status: Beta
+Although this project has already matured quite a bit, a fair amount of api polishing is still
+expected. There are unstable versions (0._x_._x_) to help users keep track
+of changes and progress.
+
 # Usage
 The best way to make use of library is with the [Official template][template].
+Check out the [guide](https://digga.divnix.com/start) to get up and running.
+Also have a look at devos's [_flake.nix_](./examples/devos/flake.nix).
+If anything is not immediately discoverable via "[`digga`][digga]'s [`mkFlake`][mk-flake], please file a bug report.
+
+# Examples
+Make sure to check out all the [examples](./examples) to see the different ways
+to make use of the digga api.
+
+## In the Wild
+You can also see digga being actually used:
+* @Pacman99: [Personal](https://gitlab.com/coffeetables/lower), [Server](https://gitlab.com/coffeetables/myrdd)
+* [@danielphan2003](https://github.com/danielphan2003/flk) and make sure to also check out [devos-ext-lib][devos-ext-lib]
+* [PubSolarOS](https://git.sr.ht/~b12f/pub-solar-os)
 
-You can also have a look at the different [examples][].
 
 # Philosophy
 
@@ -62,8 +79,48 @@ To craft well thought out APIs we need all the thoughts regarding new ideas.
 
 Pull Requests are just as amazing.
 
-# License
+# Why _flakes_?
+Flakes are a part of an explicit push to improve [Nix's UX](https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md), and have become an integral part of that effort. 
 
+They also make [Nix expressions](https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html) easier to distribute and reuse with convient [flake references](https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references) for building or using packages, modules, and whole systems.
+
+# Shoulders
+This work does not reinvent the wheel. It stands on the [shoulders of the
+following giants][giants]:
+
+## :onion: — like the layers of an onion
+- [`divnix/digga`][digga]
+- [`gytis-ivaskevicius/flake-utils-plus`][fup]
+- [`numtide/flake-utils`][fu]
+
+## :family: — like family
+- [`numtide/devshell`][devshell]
+- [`serokell/deploy-rs`][deploy]
+- [`berberman/nvfetcher`][nvfetcher]
+- [`NixOS/nixpkgs`][nixpkgs]
+
+:heart:
+
+### Inspiration & Art
+- [hlissner/dotfiles][dotfiles]
+- [nix-user-chroot](https://github.com/nix-community/nix-user-chroot)
+- [Nickel](https://github.com/tweag/nickel)
+- [Awesome Nix](https://github.com/nix-community/awesome-nix)
+- [devshell](https://github.com/numtide/devshell)
+
+# Divnix
+The divnix org is an open space that spontaneously formed out of "the Nix".
+It is really just a place where otherwise unrelated people work
+together and get stuff done.
+
+It's a place to stop "geeking out in isolation" (or within company boundaries).
+A place to experiment, learn together, and iterate quickly on best practices.
+That's what it is.
+
+It might eventually become a non-profit if that's not too complicated or, if those
+goals are sufficiently upstreamed into "the Nix", dissolved.
+
+# License
 Digga is licensed under the [MIT License][mit].
 
 [chat]: https://matrix.to/#/#devos:matrix.org
@@ -76,5 +133,5 @@ Digga is licensed under the [MIT License][mit].
 [mit]: https://mit-license.org
 [nix]: https://nixos.org/manual/nix/stable
 [nixpkgs]: https://github.com/nixos/nixpkgs
-[template]: https://github.com/divnix/devos
+[template]: ./examples/devos
 

doc/SUMMARY.md

@@ -1,6 +1,30 @@
 # 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)
+  - [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]()
+  - [Secrets](./secrets.md)
+  - [Tests](./tests.md)
+- [Helper Script – `bud`](./bud/index.md)
+  - [get](./bud/get.md)
+- [Integrations](./integrations/index.md)
+  - [Cachix](./integrations/cachix.md)
+  - [Deploy RS](./integrations/deploy.md)
+  - [NvFetcher](./integrations/nvfetcher.md)
+  - [Hercules CI](./integrations/hercules.md)
 - [API Reference](./api-reference.md)
   - [Channels](./api-reference-channels.md)
   - [Home](./api-reference-home.md)

examples/devos/CHANGELOG.md

@@ -1,114 +0,0 @@
-# Changelog
-
-## [v0.10.0](https://github.com/divnix/devos/tree/v0.10.0) (2021-05-24)
-
-**Implemented enhancements:**
-
-- Providing an interface to nixpkgs.config [\#237](https://github.com/divnix/devos/issues/237)
-- Making the user available in profiles [\#230](https://github.com/divnix/devos/issues/230)
-- copy evaluation store paths to iso [\#195](https://github.com/divnix/devos/issues/195)
-- Extract custom system builds from devosSystem out of lib [\#170](https://github.com/divnix/devos/issues/170)
-- Allow setting of channel host-wide [\#117](https://github.com/divnix/devos/issues/117)
-- alacritty: CSIu support [\#51](https://github.com/divnix/devos/issues/51)
-
-**Fixed bugs:**
-
-- Cachix timeouts + how to disable nrdxp cachix \(if needed\) [\#294](https://github.com/divnix/devos/issues/294)
-- default.nix flake-compat is broken [\#285](https://github.com/divnix/devos/issues/285)
-- All suites return "attribute missing" [\#282](https://github.com/divnix/devos/issues/282)
-- nix is built two times [\#203](https://github.com/divnix/devos/issues/203)
-- fix lib docs [\#166](https://github.com/divnix/devos/issues/166)
-
-**Closed issues:**
-
-- eliminate userFlakeNixOS [\#257](https://github.com/divnix/devos/issues/257)
-- devos-as-library [\#214](https://github.com/divnix/devos/issues/214)
-
-**Merged pull requests:**
-
-- Update evalArgs to match the new planned API [\#239](https://github.com/divnix/devos/pull/239)
-
-## [v0.9.0](https://github.com/divnix/devos/tree/v0.9.0) (2021-04-19)
-
-**Implemented enhancements:**
-
-- pin inputs into iso live registry [\#190](https://github.com/divnix/devos/issues/190)
-- Pass 'self' to lib [\#169](https://github.com/divnix/devos/issues/169)
-- doc: quickstart "ISO. What next?" [\#167](https://github.com/divnix/devos/issues/167)
-- Integrate Android AOSP putting mobile under control [\#149](https://github.com/divnix/devos/issues/149)
-- Inoculate host identity on first use [\#132](https://github.com/divnix/devos/issues/132)
-- kubenix support [\#130](https://github.com/divnix/devos/issues/130)
-- Improve Home Manager support: profiles/suites, modules, extern, flake outputs [\#119](https://github.com/divnix/devos/issues/119)
-- Local CA \(between hosts\) [\#104](https://github.com/divnix/devos/issues/104)
-- Q5: git annex for machine state [\#68](https://github.com/divnix/devos/issues/68)
-- name space ./pkgs overlays [\#60](https://github.com/divnix/devos/issues/60)
-- remap global keys easily [\#57](https://github.com/divnix/devos/issues/57)
-- make pass state part of this repo's structure [\#56](https://github.com/divnix/devos/issues/56)
-- Incorporate ./shells [\#38](https://github.com/divnix/devos/issues/38)
-- Encrypt with \(r\)age [\#37](https://github.com/divnix/devos/issues/37)
-
-**Fixed bugs:**
-
-- `pathsToImportedAttrs` does not accept directories [\#221](https://github.com/divnix/devos/issues/221)
-- Cachix caches aren't added to the configuration [\#208](https://github.com/divnix/devos/issues/208)
-- Issues with current changelog workflow [\#205](https://github.com/divnix/devos/issues/205)
-- iso: systemd service startup [\#194](https://github.com/divnix/devos/issues/194)
-- Help adding easy-hls-nix to devos [\#174](https://github.com/divnix/devos/issues/174)
-- `flk update` fails because of obsolete flag [\#159](https://github.com/divnix/devos/issues/159)
-- Expected that not all packages are exported? [\#151](https://github.com/divnix/devos/issues/151)
-- Segmentation fault when generating iso [\#150](https://github.com/divnix/devos/issues/150)
-
-**Documentation:**
-
-- doc: split iso [\#193](https://github.com/divnix/devos/issues/193)
-- lib: can depend on pkgs \(a la nixpkgs\#pkgs/pkgs-lib\) [\#147](https://github.com/divnix/devos/pull/147)
-
-**Closed issues:**
-
-- FRRouting router implementation [\#154](https://github.com/divnix/devos/issues/154)
-- ARM aarch64 Support [\#72](https://github.com/divnix/devos/issues/72)
-
-## [v0.8.0](https://github.com/divnix/devos/tree/v0.8.0) (2021-03-02)
-
-**Implemented enhancements:**
-
-- semi automatic update for /pkgs [\#118](https://github.com/divnix/devos/issues/118)
-- Home-manager external modules from flakes [\#106](https://github.com/divnix/devos/issues/106)
-
-**Fixed bugs:**
-
-- My emacsGcc overlay is not working  [\#146](https://github.com/divnix/devos/issues/146)
-- local flake registry freezes branches [\#142](https://github.com/divnix/devos/issues/142)
-- nixos-option no longer works after collect garbage [\#138](https://github.com/divnix/devos/issues/138)
-- Profiles imports are brittle, causing failure if imported twice [\#136](https://github.com/divnix/devos/issues/136)
-
-## [0.7.0](https://github.com/divnix/devos/tree/0.7.0) (2021-02-20)
-
-**Implemented enhancements:**
-
-- add zoxide [\#53](https://github.com/divnix/devos/issues/53)
-- Multiarch support? [\#17](https://github.com/divnix/devos/issues/17)
-- initial multiArch support [\#18](https://github.com/divnix/devos/pull/18)
-
-**Fixed bugs:**
-
-- Missing shebang from flk.sh [\#131](https://github.com/divnix/devos/issues/131)
-- Rename Meta Issue [\#128](https://github.com/divnix/devos/issues/128)
-- specialisations break the `system` argument [\#46](https://github.com/divnix/devos/issues/46)
-- Revert "Add extraArgs to lib.nixosSystem call to add system args." [\#47](https://github.com/divnix/devos/pull/47)
-
-**Documentation:**
-
-- update home-manager urls [\#62](https://github.com/divnix/devos/pull/62)
-
-**Closed issues:**
-
-- add github action for cachix build ci [\#59](https://github.com/divnix/devos/issues/59)
-
-## [12052020](https://github.com/divnix/devos/tree/12052020) (2020-12-06)
-
-## [07092020](https://github.com/divnix/devos/tree/07092020) (2020-07-09)
-
-
-
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

examples/devos/README.md

@@ -1,95 +1,10 @@
-[![NixOS](https://img.shields.io/badge/NixOS-unstable-blue.svg?style=flat&logo=NixOS&logoColor=white)](https://nixos.org)
-[![MIT License](https://img.shields.io/github/license/divnix/devos)][mit]
-[![Chat](https://img.shields.io/matrix/devos:nixos.org.svg?label=%23devos%3Anixos.org&logo=matrix&server_fqdn=matrix.org)][matrix]
+# Nix Configuration
+This repository is home to the nix code that builds my systems.
 
-> #### ⚠ Advisory ⚠
-> DevOS requires the [flakes][flakes] feature available via an _experimental_
-> branch of [nix][nix]. Until nix 2.4 is released, this project
-> should be considered unstable.
+## Why Nix?
+Nix allows for easy to manage, collaborative, reproducible deployments. This means that once something is setup and configured once, it works forever. If someone else shares their configuration, anyone can make use of it.
 
-### Why?
-Make an awesome template for NixOS users, with consideration for common tools like [home-manager][home-manager],
-[devshell][devshell], and [more](./doc/integrations).
 
-### No. Why _flakes_?
-Flakes are a part of an explicit push to improve [Nix's UX](https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md), and have become an integral part of that effort. 
+This flake is configured with the use of [digga][digga].
 
-They also make [Nix expressions](https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html) easier to distribute and reuse with convient [flake references](https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references) for building or using packages, modules, and whole systems.
-
-## Getting Started
-Check out the [guide](https://devos.divnix.com/start) to get up and running.
-Also, have a look at [_flake.nix_](./flake.nix). If anything is not immediately 
-discoverable via "[`digga`][digga]'s [`mkFlake`][mk-flake],
-please file a bug report.
-
-### Status: Beta
-Although this project has already matured quite a bit, especially through
-recent outfactoring of [`digga`][digga], a fair amount of api polishing is still
-expected. There are unstable versions (0._x_._x_) to help users keep track
-of changes and progress, and a [`develop`](https://github.com/divnix/devos/tree/develop) branch for the brave 😜
-
-## In the Wild
-* @Pacman99: [Personal](https://gitlab.com/coffeetables/lower), [Server](https://gitlab.com/coffeetables/myrdd)
-* [@danielphan2003](https://github.com/danielphan2003/flk) and make sure to also check out [devos-ext-lib][devos-ext-lib]
-* [PubSolarOS](https://git.sr.ht/~b12f/pub-solar-os)
-
-## Shoulders
-This work does not reinvent the wheel. It stands on the [shoulders of the
-following giants][giants]:
-
-### :onion: — like the layers of an onion
-- [`divnix/digga`][digga]
-- [`gytis-ivaskevicius/flake-utils-plus`][fup]
-- [`numtide/flake-utils`][fu]
-
-### :family: — like family
-- [`numtide/devshell`][devshell]
-- [`serokell/deploy-rs`][deploy]
-- [`berberman/nvfetcher`][nvfetcher]
-- [`NixOS/nixpkgs`][nixpkgs]
-
-:heart:
-
-## Inspiration & Art
-- [hlissner/dotfiles][dotfiles]
-- [nix-user-chroot](https://github.com/nix-community/nix-user-chroot)
-- [Nickel](https://github.com/tweag/nickel)
-- [Awesome Nix](https://github.com/nix-community/awesome-nix)
-- [devshell](https://github.com/numtide/devshell)
-
-## Divnix
-The divnix org is an open space that spontaneously formed out of "the Nix".
-It is really just a place where otherwise unrelated people work
-together and get stuff done.
-
-It's a place to stop "geeking out in isolation" (or within company boundaries).
-A place to experiment, learn together, and iterate quickly on best practices.
-That's what it is.
-
-It might eventually become a non-profit if that's not too complicated or, if those
-goals are sufficiently upstreamed into "the Nix", dissolved.
-
-# License
-DevOS is licensed under the [MIT License][mit].
-
-[community]: https://github.com/divnix/devos/tree/community
-[core]: https://github.com/divnix/devos
-[deploy]: https://github.com/serokell/deploy-rs
-[devshell]: https://github.com/numtide/devshell
 [digga]: https://github.com/divnix/digga
-[dotfiles]: https://github.com/hlissner/dotfiles
-[flake-doc]: https://github.com/NixOS/nix/blob/master/src/nix/flake.md
-[flakes]: https://nixos.wiki/wiki/Flakes
-[fu]: https://github.com/numtide/flake-utils
-[fup]: https://github.com/gytis-ivaskevicius/flake-utils-plus
-[giants]: https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants
-[home-manager]: https://nix-community.github.io/home-manager
-[mit]: https://mit-license.org
-[mk-flake]: https://github.com/divnix/digga/tree/main/src/mkFlake
-[nix]: https://nixos.org/manual/nix/stable
-[nixos]: https://nixos.org/manual/nixos/stable
-[nixpkgs]: https://github.com/NixOS/nixpkgs
-[nvfetcher]: https://github.com/berberman/nvfetcher
-[please]: https://github.com/nrdxp/devos/tree/nrd
-[matrix]: https://matrix.to/#/#devos:nixos.org
-[devos-ext-lib]: https://github.com/divnix/devos-ext-lib

examples/devos/bors.toml

@@ -1,5 +0,0 @@
-status = [ "check" ]
-
-required_approvals = 1
-
-up_to_date_approvals = true

examples/devos/doc/.gitignore

@@ -1 +0,0 @@
-book

examples/devos/doc/CONTRIBUTING.md

@@ -1,18 +0,0 @@
-# Pull Requests
-
-## TL;DR;
-- **Target Branch**: `main`
-- **Merge Policy**: [`bors`][bors] is always right (→ `bors try`)
-- **Docs**: every changeset is expected to contain doc updates
-- **Commit Msg**: be a poet! Comprehensive and explanatory commit messages 
-  should cover the motivation and use case in an easily understandable manner
-  even when read after a few months.
-- **Test Driven Development**: please default to test driven development where possible.
-
-### Within the Devshell (`nix develop`)
-- **Hooks**: please `git commit` within the devshell
-- **Fail Early**: please run from within the devshell on your local machine:
-  - `nix flake check`
-
-[bors]: https://bors.tech
-

examples/devos/doc/SUMMARY.md

@@ -1,28 +0,0 @@
-# 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)
-  - [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]()
-  - [Secrets](./secrets.md)
-  - [Tests](./tests.md)
-- [Helper Script – `bud`](./bud/index.md)
-  - [get](./bud/get.md)
-- [Integrations](./integrations/index.md)
-  - [Cachix](./integrations/cachix.md)
-  - [Deploy RS](./integrations/deploy.md)
-  - [NvFetcher](./integrations/nvfetcher.md)
-  - [Hercules CI](./integrations/hercules.md)
-- [Contributing](./CONTRIBUTING.md)

examples/devos/doc/book.toml

@@ -1,6 +0,0 @@
-[book]
-authors = ["Timothy DeHerrera"]
-language = "en"
-multilingual = false
-src = "."
-title = "devos docs"

examples/devos/doc/tests.md

@@ -1,33 +0,0 @@
-# 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).
-
-## Unit Tests
-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 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,
-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/main/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