Documentation overhaul

README.md

@@ -17,121 +17,17 @@ 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 want to get a taste of Nix-Doom-Emacs, you can run: 
 
-``` 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;
-              };
-            }
-          ];
-        })
-      ];
-    };
-  };
-}
+$ nix run github:nix-community/nix-doom-emacs
 ```
 
-## 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
+Which will run Nix-Doom-Emacs with an example configuration. 
+Continue to [the documentation](./docs) to learn how to customise your setup further to your needs.
 
-## 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,194 @@
+# 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 using (and especially debugging) Nix and Emacs Lisp before using this project.
+
+If you encounter any issues that make it unusable 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/nix-community/nix-straight.el), and that you understand the consequences.
+
+# 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. This uses the `devShell` (or `nix-shell` feature if you're using non-flakes, which is not recommended) feature of Nix.
+
+### Flake
+
+```nix
+{
+  description = "nix-doom-emacs shell";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
+  };
+
+  outputs = { self, nixpkgs, nix-doom-emacs, ... }:
+  let
+    system = "x86_64-linux";
+    pkgs = import nixpkgs { inherit system; };
+    doom-emacs = nix-doom-emacs.packages.${system}.default.override {
+      doomPrivateDir = ./doom.d;
+    };
+  in
+  {
+    devShells.${system}.default = pkgs.mkShell {
+      buildInputs = [ doom-emacs ];
+    };
+  };
+}
+```
+
+### Non-Flake
+```nix
+{ pkgs ? import <nixpkgs> { } }:
+
+let
+  repo = pkgs.fetchFromGitHub {
+    owner = "nix-community";
+    repo = "nix-doom-emacs";
+    rev = "<commit>";
+    sha256 = "<hash>";
+  };
+  nix-doom-emacs = pkgs.callPackage (import repo) {
+    doomPrivateDir = ./doom.d;
+  };
+in
+pkgs.mkShell {
+  buildInputs = [ nix-doom-emacs ];
+}
+```