bahaghari: update README

subprojects/bahaghari/README.adoc

@@ -1,31 +1,127 @@
 = Bahaghari
 :toc:
 
+:fn-container-comment: footnote:[IDK why would someone do this with Bahaghari but whatever, your system, your rules.]
+:fn-specialization-comment: footnote:[Which I can see is useful for separating rices and booting into them separately for whatever reason (again, your system, your rules but my guess is because you're a control freak).]
 
-Bahaghari (Tagalog word for "rainbow") is a specialized set of Nix modules for generating and applying themes.
+
+Bahaghari (Tagalog word for "rainbow" or a "king's loincloth" if you prefer) is a specialized set of Nix modules for generating and applying themes.
 Mainly useful for making your ricing process with NixOS and home-manager environments easier.
 This module set should allow for some flexibility for your use case.
 
 At its current state, Bahaghari is considered unstable and might have breaking changes more than what you'd expect.
 
 
+
+
+[#getting-started]
+== Getting started
+
+To get started using Bahaghari, you have to set some things up first.
+The way how Bahaghari expects you to use it is by choosing one (or more if you want) of the module sets which you can view more details at <<module-sets, its dedicated section>>.
+For now, let's assume that you are using Tinted Theming module set in your NixOS configuration which you can set it up with the following code.
+
+// TODO: Change all of the URLs once this moves into its own repo.
+First, you'll have to install Bahaghari as part of your Nix project or whatever.
+There are multiple ways to do this.
+
+* We'll first start with the increasingly popular method of including Nix dependencies with https://zero-to-nix.com/concepts/flakes[Nix flakes], a built-in way of pinning them dependencies.
++
+[source, nix]
+----
+{
+  inputs.bahaghari.url = "github:foo-dogsquared/nixos-config?dir=subprojects/bahaghari";
+
+  # ...
+
+  outputs = { nixpkgs, ... }@inputs: {
+    nixosConfigurations = nixpkgs.lib.nixosSystem {
+      modules = [
+        inputs.bahaghari.nixosModules.bahaghari
+      ];
+    };
+  };
+}
+----
+
+* You can also import the dependencies with a pinning tool (that is not flakes) like https://github.com/nmattia/niv[niv].
++
+[source, shell]
+----
+# I would recommend to rename this into more specific package name.
+niv add foo-dogsquared/nixos-config --name foo-dogsquared-nixos-config
+----
++
+Then somewhere in your Nix code, you can add it like in the following listing.
++
+[source, nix]
+----
+let
+  sources = import ./nix/sources.nix;
+  bahaghari = import "${sources.foo-dogsquared-nixos-config}/subprojects/bahaghari" { };
+in
+{
+  imports = [ bahaghari.nixosModules.bahaghari ];
+}
+----
+
+* Lastly, you can import it through https://zero-to-nix.com/concepts/channels[channels].
++
+[source, shell]
+----
+# You'll likely to run this as root since you'll be dealing with your NixOS
+# system after all.
+nix-channel --add "https://github.com/foo-dogsquared/nixos-config/archive/master.tar.gz" foo-dogsquared-nixos-config
+----
++
+Similarly to importing it through niv, you can now use it somewhere in your Nix code.
++
+[source, nix]
+----
+{ config, lib, ... }:
+
+let
+  bahaghari = import <foo-dogsquared-nixos-config/subprojects/bahaghari> { };
+in
+{
+  imports = [ bahaghari.nixosModules.bahaghari ];
+}
+----
+
+Importing the module will also import Bahaghari's library set (`bahaghariLib`), making it available as `bahaghariLib` module argument.
+
+If for whatever reason you need Bahaghari library outside of using it with Bahaghari, you can also import it yourself.
+Here's one way to set it to be available in the module of your environment.
+
+[source, nix]
+----
+{ pkgs, ... }:
+
+let
+  # This is assuming you have Bahaghari as part of NIX_PATH.
+  bahaghari = import <foo-dogsquared-nixos-config/subprojects/bahaghari> { };
+in
+{
+  _module.args.bahaghariLib =
+    import bahaghari.bahaghariLib { inherit pkgs };
+}
+----
+
+
+
+
+[#module-sets]
 == Module sets
 
 As a whole, Bahaghari is more like a set of sets, a metaset, if you will.
 Specifically, it is composed of module sets of which has different ways to use them.
 Here is the exhaustive list of them and its details.
 
+
+[#tinted-theming]
 === Tinted Theming
 
 Bahaghari has a module set for interacting with Tinted Theming standard schemes and templates.
-To use it, simply import it and you're pretty much set.
-
-// TODO: Nix code importing here
-
-Optionally, you can also import Bahaghari's library set for Tinted Theming.
-Like most of the library components from Bahaghari, it requires both the `pkgs` and `lib` attribute found from the standard nixpkgs module system.
-
-// TODO: Nix code importing BahagharLib for TT. Also code samples for it.
 
 This module is designed to closely follow Tinted Theming's standard while offering some convenience with the library set.
 For example, you can use `importYAML` from Bahaghari's standard library set to easily import standard Base16 schemes into Nix-representable data which you can press onto your Nix configuration.
@@ -33,6 +129,7 @@ For example, you can use `importYAML` from Bahaghari's standard library set to e
 // TODO: GNOME HIG module set
 // TODO: Material You module set
 
+[#templated-configuration-sub-modules]
 === Templated configuration sub-modules
 
 Bahaghari offers a pre-configured version of already existing modules for NixOS, home-manager, and NixVim quite similar to Stylix's `stylix.targets.<name>` submodules.
@@ -41,20 +138,90 @@ To make use of this, you'll have to import Bahaghari module set's
 // TODO: Pictures and sample configurations
 
 
+[#comparison-with-other-modules]
 == Comparison with other modules
 
+[#nix-colors]
 === nix-colors
 
 Bahaghari initially started as a derivative to nix-colors as a single Nix module entirely dedicated for Tinted Theming standard.
 It was created to address its limitation of allowing only one colorscheme at a time which limits a lot of possible applications.
-Most notably, the feature I'm looking for is generating multiple colorscheme templates for different applications which is nice for hybrid deployments of home-manager-plus-mutable-configurations (AKA traditional dotfiles).
+Most notably, the feature I'm looking for is generating multiple colorscheme templates for different applications which is nice for hybrid deployments of home-manager-plus-mutable-configurations (AKA traditional dotfiles) and for mixed installations of NixOS and home-manager (or whatever else that can be combined).
 
 While Bahaghari eventually diverged from nix-colors entirely, it can be used as an alternative specifically with Bahaghari's Tinted Theming module set.
-You can replicate nix-colors' preference of allowing a default set of colorscheme
+You can replicate nix-colors' preference of allowing a default set of colorscheme by creating a module argument holding the name of the preferred colorscheme.
+Here's one way to implement it.
 
-== Stylix
+[source, nix]
+----
+{ bahaghariLib, ... }:
 
-While Bahaghari can be used similarly to Stylix, it isn't completely 1-to-1 to Stylix as it focuses on the holistic side of customization including for fonts and wallpaper.
+{
-On the other hand, Bahaghari completely focuses on colorscheme generation. footnote:[While Bahaghari as a project can also focus beyond colorschemes similar to Stylix, it isn't a part of the vision for now. Who knows, it might be. ;)]
+  bahaghari.tinted-theming.schemes.bark-on-a-tree =
+    bahaghariLib.importYAML ./base16-bark-on-a-tree.yml;
 
-Bahaghari also took some cues from Stylix specifically from its Stylix targets which became the pre-templated configurations submodules for each of the module set.
+  # Just assume there's importing more schemes here.
+
+  _module.args.defaultTintedThemingScheme = "bark-on-a-tree";
+}
+----
+
+
+
+
+[#stylix]
+=== Stylix
+
+While Bahaghari can be used similarly to Stylix, it isn't completely 1-to-1 to Stylix as the latter focuses on the holistic side of customization including for fonts and wallpaper.
+On the other hand, Bahaghari completely focuses on colorscheme generation. footnote:[While Bahaghari as a project can also focus beyond colorschemes similar to Stylix, it isn't a part of the vision for now.]
+
+Bahaghari also took some cues from Stylix specifically from its Stylix targets which became the pre-templated configurations submodules for each of the design system module set (e.g., Tinted Theming).
+
+
+
+
+[#hacking-this-project]
+== Hacking this project
+
+If you want to hack this hack, you can do so with Nix.
+This is mostly a Nix project so you only need Nix and you're good to go.
+
+The folder structure of this project should be intuitive but we'll give a recap like a good manager.
+Here's the rundown.
+
+* link:./default.nix[./default.nix] is basically the entrypoint for our user and onlookers who're looking to extend Bahaghari.
+This is used both by the flake- and non-flake-based setups for consistency (and also easier to maintain).
+
+* link:./lib/[./lib/] is where the Bahaghari library set lives.
+It takes a lot of cues from nixpkgs how the library is maintained with individual files separated by purpose and the module sets (most of the time).
+
+* link:./modules/[./modules/] is where the Bahaghari module sets reside.
+All of them are then separated by... module sets and are organized by the aforementioned `default.nix`.
+
+* link:./tests/[./tests/] is where the test suites reside.
+We'll cover how to interact with the test suite right after this section.
+
+
+[#testing]
+=== Testing
+
+This project comes with a test suite for... testing things.
+You know, for the purpose of preventing as much regression and catching as many potential bugs before releasing this for the users.
+
+For the Bahaghari library set, we have a testing infrastructure set all set in link:./tests/[`./tests/`].
+This relies on the `lib.debug.runTests` from nixpkgs which is enough for our simple needs of making sure the functions are correct.
+To run the test suite, here's one way to do it.footnote:test-setup-assumption[Assuming you have the new Nix CLI and have nixpkgs as part of `NIX_PATH`.]
+
+[source, shell]
+----
+nix eval -f ./tests lib
+----
+
+We also have a test suites for the Nix module sets.
+Similarly from the library set testing, it relies on nixpkgs' NixOS test integration.footnote:[For now, we only test these with NixOS since most of Bahaghari is environment-agnostic anyways. We're more concerned if it can used as intended.]
+You can test those puppies out with the following command.footnote:test-setup-assumption[]
+
+[source, shell]
+----
+nix eval -f ./tests modules
+----