Documentation overhaul

README.md

@@ -17,121 +17,9 @@ some may not be fully compatible as the version available in NixOS or
 [emacs-overlay](https://github.com/nix-community/emacs-overlay) may not be
 compatible with the `doom-emacs` requirements.
 
-## Getting started
+# Quick Start
 
-Using [home-manager](https://github.com/nix-community/home-manager):
+If you're impatient, you can run ``nix run github:nix-community/nix-doom-emacs``. If you want to use it more extensively, then you should continue reading [the documentation](./docs)
 
-``` nix
-{ pkgs, ... }:
-
-let
-  doom-emacs = pkgs.callPackage (builtins.fetchTarball {
-    url = https://github.com/nix-community/nix-doom-emacs/archive/master.tar.gz;
-  }) {
-    doomPrivateDir = ./doom.d;  # Directory containing your config.el init.el
-                                # and packages.el files
-  };
-in {
-  home.packages = [ doom-emacs ];
-}
-```
-
-`./doom.d` should contain the following three files: `config.el`, `init.el` and
-`packages.el`. If you don't already have an existing `doom-emacs` configuration,
-you can use the contents of `test/doom.d` as a template.
-
-Using `flake.nix`:
-
-``` nix
-{
-  inputs = {
-    home-manager.url = "github:nix-community/home-manager";
-    nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
-  };
-
-  outputs = {
-    self,
-    nixpkgs,
-    lib,
-    home-manager,
-    nix-doom-emacs,
-    ...
-  }: {
-    nixosConfigurations.exampleHost = lib.nixosSystem {
-      system = "x86_64-linux";
-      modules = [
-        home-manager.nixosModules.home-manager
-        ({
-          home-manager.users.exampleUser = lib.mkMerge [
-            nix-doom-emacs.hmModule
-            { ... }: {
-              programs.doom-emacs = {
-                enable = true;
-                doomPrivateDir = ./doom.d;
-              };
-            }
-          ];
-        })
-      ];
-    };
-  };
-}
-```
-
-## Under the hood
-
-This expression leverages
-[nix-straight.el](https://github.com/nix-community/nix-straight.el) under the hood for
-installing dependencies. The restrictions of that package apply here too.
-
-## Usage
-
-instead of running emacs.d/bin/doom, once you have update your config files (packages.el, init.el, config.el), rebuild doom-emacs with nix. If you are using home-manager, simply run `home-manager switch`
-
-## Troubleshooting
-
-On macOS on a fresh install, you might run into the error `Too many files open`. running `ulimit -S -n 2048` will only work for the duration of your shell and will fix the error
-
-## Installing emacs packages
-
-In the initial packages.el instructions for how to install packages can be
-found. However some packages might require a particular software dependency to
-be installed. Trying to install those would give you an error of the type:
-`Searching for program: No such file or directory, git` (Missing git dependency)
-Here is how you would go installing
-[magit-delta](https://github.com/dandavison/magit-delta) for example (which
-requires git).
-
-Under the line:
-`doomPrivateDir = ./doom.d;`
-in your configuration, you would add the following:
-
-```Nix
-{
-  emacsPackagesOverlay = self: super: {
-     magit-delta = super.magit-delta.overrideAttrs (esuper: {
-       buildInputs = esuper.buildInputs ++ [ pkgs.git ];
-     });
-  };
-}
-```
-
-To make the git dependency available. trying to rebuild doom-emacs with
-`home-manager switch` should work correctly now.
-
-## Using the daemon
-
-To use the daemon, simply enable the emacs service (with `NixOS`, `home-manager`
-or `nix-darwin`) and use the doom emacs package. `doom-emacs` will need to be
-referenced at the top of your config file.
-
-```nix
-{
-  services.emacs = {
-    enable = true;
-    package = doom-emacs; # Not needed if you're using the Home-Manager module instead
-  };
-}
-```
-
-to connect to the daemon you can now run `emacsclient -c`
+# Documentation
+To know how to use Nix-Doom-Emacs, and to fix other issues, check the [documentation](./docs)

docs/README.md

@@ -0,0 +1,151 @@
+# Documentation for Nix-Doom-Emacs
+
+Nix-Doom-Emacs (also commonly referred to as NDE in chatrooms) is a project with lots of moving pieces and hacks. Users are expected to know their way around Nix and Emacs (also Emacs Lisp) before using this project, and users should expect to have to debug things.
+
+If you encounter any issues that make it not usable to you (or if you need support), please talk to us first in the [Matrix room](https://matrix.to/#/#doom-emacs:nixos.org) and if it's indeed a bug of Nix-Doom-Emacs, file it in the [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues).
+
+If you find this documentation unclear or incomplete, please let us know as well.
+
+Here's the [FAQ](./faq.md)
+
+Nix-Doom-Emacs uses [`nix-straight.el`](https://github.com/nix-community/nix-straight.el) under the hood to install dependencies. It's a low level wrapper to add Nix integration over [`straight.el`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. 
+
+Before using Nix-Doom-Emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/radian-software/straight.el) and that you understand the limitations.
+
+If you're not aware yet, then:
+
+#### **WARNING**: HERE BE DRAGONS! This project expects fairly advanced and experienced users.
+
+# Getting Started
+
+To get started, we suggest these methods. They are ordered from most suggested to least suggested.
+In all of these methods, you'll need your Doom Emacs configuration. It should contain the following three files: 
+`config.el`, `init.el` and `packages.el`. If you don't already have an existing `doom-emacs` configuration, you can use the contents of `test/doom.d` as a template.
+
+The Doom configuration will be referred to as `./doom.d` in these snippets. You can name it whatever you like.
+
+## Flake + Home-Manager
+
+`File: flake.nix`
+```nix
+{
+  inputs = {
+    home-manager.url = "github:nix-community/home-manager";
+    nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    lib,
+    home-manager,
+    nix-doom-emacs,
+    ...
+  }:
+    let
+      system      = "x86_64-linux";
+      specialArgs = { inherit inputs; };
+    in {
+    nixosConfigurations.exampleHost = lib.nixosSystem {
+      inherit system specialArgs;
+      modules = [
+        ./default.nix
+        home-manager.nixosModules.home-manager
+        {
+          home-manager.users.exampleUser.imports = [ ./home.nix ];
+        }
+      ];
+    };
+  };
+}
+
+```
+
+`File: home.nix`
+```nix
+{ config, pkgs, inputs, ... }: {
+  imports = [ inputs.nix-doom-emacs.hmModule ];
+
+  # ...
+  programs.doom-emacs = {
+    enable = true;
+    doomPrivateDir = ./doom.d; # Directory containing your config.el, init.el
+                               # and packages.el files
+  };
+  # ...
+}
+```
+
+## Non-Flake Home-Manager
+
+```nix
+{ pkgs, ... }:
+
+let
+  doom-emacs = pkgs.callPackage (builtins.fetchTarball {
+    url = https://github.com/nix-community/nix-doom-emacs/archive/master.tar.gz;
+  }) {
+    doomPrivateDir = ./doom.d;  # Directory containing your config.el, init.el
+                                # and packages.el files
+  };
+in {
+  home.packages = [ doom-emacs ];
+}
+```
+
+
+## NixOS
+
+Using Nix-Doom-Emacs without Home-Manager isn't recommended, especially if you're a beginner.
+
+`File: flake.nix`
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    lib,
+    nix-doom-emacs,
+    ...
+  }:
+    let
+      system      = "x86_64-linux";
+      specialArgs = { inherit inputs; };
+    in {
+    nixosConfigurations.exampleHost = lib.nixosSystem {
+      inherit system specialArgs;
+      modules = [
+        ./default.nix
+        # ...
+      ];
+    };
+  };
+}
+```
+
+`File: default.nix`
+```nix
+{ config, nixpkgs, lib, inputs }: {
+  # ...
+  environment.systemPackages = 
+    let
+      doom-emacs = inputs.nix-doom-emacs.packages.${system}.default.override {
+        doomPrivateDir = ./doom;
+      };
+    in [
+      doom-emacs
+    ];
+  # ...
+}
+```
+
+For what it's worth, you can see all overridable parameters of Nix-Doom-Emacs in [default.nix](../default.nix).
+
+## Standalone
+
+This is the least recommended method.