Merge pull request #1027 from NotAShelf/notashelf/push-nrwtqmomkswt

docs: add flakeless examples; describe flakes prerequisites

docs/manual/installation/modules/flakes.md

@@ -0,0 +1,33 @@
+### Prerequisites {#sec-flakes-prerequisites}
+
+To install nvf with flakes, you must make sure the following requirements are
+met.
+
+1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later
+   version of Nix from nixpkgs.
+2. Flake-related experimental features must be enabled. Namely, you need
+   `nix-command` and `flakes`. Some Nix vendors enable those by default, please
+   consult their documentation if you are not using mainstream Nix.
+   - When using NixOS, add the following to your `configuration.nix` and rebuild
+     your system.
+
+     ```nix
+     nix.settings.experimental-features = "nix-command flakes";
+     ```
+
+   - If you are not using NixOS, add the following to `nix.conf` (located at
+     `~/.config/nix/` or `/etc/nix/nix.conf`).
+
+     ```bash
+     experimental-features = nix-command flakes
+     ```
+
+   - You may need to restart the Nix daemon with, for example,
+     `sudo systemctl restart nix-daemon.service`.
+
+   - Alternatively, you can enable flakes on a per-command basis with the
+     following additional flags to `nix` and `home-manager`:
+
+     ```sh
+     $ nix --extra-experimental-features "nix-command flakes" <sub-commands>
+     ```

docs/manual/installation/modules/home-manager.md

@@ -5,9 +5,18 @@ inside the home-manager configuration without having to call for the wrapper
 yourself. It is the recommended way to use **nvf** alongside the NixOS module
 depending on your needs.
 
-To use it, we first add the input flake.
+## With Flakes {#sec-hm-flakes}
+
+```{=include=}
+flakes.md
+```
+
+### Usage {#sec-hm-flakes-usage}
+
+To use **nvf** with flakes, we first need to add the input to our `flake.nix`.
 
 ```nix
+# flake.nix
 {
   inputs = {
     # Optional, if you intend to follow nvf's obsidian-nvim input
@@ -16,7 +25,7 @@ To use it, we first add the input flake.
 
     # Required, nvf works best and only directly supports flakes
     nvf = {
-      url = "github:notashelf/nvf";
+      url = "github:NotAShelf/nvf";
       # You can override the input nixpkgs to follow your system's
       # instance of nixpkgs. This is safe to do as nvf does not depend
       # on a binary cache.
@@ -25,6 +34,8 @@ To use it, we first add the input flake.
       # for example:
       inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
     };
+
+    # ...
   };
 }
 ```
@@ -39,7 +50,7 @@ Followed by importing the home-manager module somewhere in your configuration.
 }
 ```
 
-## Example Installation {#sec-example-installation-hm}
+### Example Installation {#sec-example-installation-hm}
 
 ```nix
 {
@@ -66,7 +77,8 @@ Once the module is properly imported by your host, you will be able to use the
 `programs.nvf` module option anywhere in your configuration in order to
 configure **nvf**.
 
-```nix{
+```nix
+{
   programs.nvf = {
     enable = true;
     # your settings need to go into the settings attribute set
@@ -89,3 +101,45 @@ installation sections of the manual. You may find all available options in the
 [appendix](https://notashelf.github.io/nvf/options)
 
 :::
+
+## Without Flakes {#sec-hm-flakeless}
+
+As of v0.8, it is possible to install **nvf** on a system if you are not using
+flakes. This is possible thanks to the flake-compat project.
+
+To get started, you must fetch the repository using `builtins.fetchTarball` or a
+similar mechanism.
+
+```nix
+# home.nix
+let
+  nvf = import (builtins.fetchTarball {
+    url = "https://github.com/notashelf/nvf/archive/<commit or tag>.tar.gz";
+    # Optionally, you can add 'sha256' for verification and caching
+    # sha256 = "<sha256>";
+  });
+in {
+  imports = [
+    # Import the NixOS module from your fetched input
+    nvf.homeManagerModules.nvf
+  ];
+
+  # Once the module is imported, you may use `programs.nvf` as exposed by the
+  # NixOS module.
+  programs.nvf.enable = true;
+}
+```
+
+[npins]: https://github.com/andir/npins
+[niv]: https://github.com/nmattia/niv
+
+::: {.tip}
+
+Nix2 does not have a builtin lockfile mechanism like flakes. As such you must
+manually update the URL and hash for your input. This is annoying to deal with,
+and most users choose to defer this task to projects such as [npins] or [niv].
+If you are new to NixOS, I encourage you to look into Flakes and see if they fit
+your use case. Alternatively, look into the aforementioned projects for more
+convenient dependency management mechanisms.
+
+:::

docs/manual/installation/modules/nixos.md

@@ -5,9 +5,18 @@ the NixOS configuration without having to call for the wrapper yourself. It is
 the recommended way to use **nvf** alongside the home-manager module depending
 on your needs.
 
-To use it, we first add the input flake.
+## With Flakes {#sec-nixos-flakes}
+
+```{=include=}
+flakes.md
+```
+
+### Usage {#sec-nixos-flakes-usage}
+
+To use **nvf** with flakes, we first need to add the input to our `flake.nix`.
 
 ```nix
+# flake.nix
 {
   inputs = {
     # Optional, if you intend to follow nvf's obsidian-nvim input
@@ -16,7 +25,7 @@ To use it, we first add the input flake.
 
     # Required, nvf works best and only directly supports flakes
     nvf = {
-      url = "github:notashelf/nvf";
+      url = "github:NotAShelf/nvf";
       # You can override the input nixpkgs to follow your system's
       # instance of nixpkgs. This is safe to do as nvf does not depend
       # on a binary cache.
@@ -25,6 +34,8 @@ To use it, we first add the input flake.
       # for example:
       inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
     };
+
+    # ...
   };
 }
 ```
@@ -39,7 +50,7 @@ Followed by importing the NixOS module somewhere in your configuration.
 }
 ```
 
-## Example Installation {#sec-example-installation-nixos}
+### Example Installation {#sec-example-installation-nixos}
 
 ```nix
 {
@@ -64,10 +75,12 @@ Once the module is properly imported by your host, you will be able to use the
 `programs.nvf` module option anywhere in your configuration in order to
 configure **nvf**.
 
-```nix{
+```nix
+{
   programs.nvf = {
     enable = true;
-    # your settings need to go into the settings attribute set
+    
+    # Your settings need to go into the settings attribute set
     # most settings are documented in the appendix
     settings = {
       vim.viAlias = false;
@@ -87,3 +100,45 @@ installation sections of the manual. You may find all available options in the
 [appendix](https://notashelf.github.io/nvf/options)
 
 :::
+
+## Without Flakes {#sec-nixos-flakeless}
+
+As of v0.8, it is possible to install **nvf** on a system if you are not using
+flakes. This is possible thanks to the flake-compat project.
+
+To get started, you must fetch the repository using `builtins.fetchTarball` or a
+similar mechanism.
+
+```nix
+# configuration.nix
+let
+  nvf = import (builtins.fetchTarball {
+    url = "https://github.com/notashelf/nvf/archive/<commit or tag>.tar.gz";
+    # Optionally, you can add 'sha256' for verification and caching
+    # sha256 = "<sha256>";
+  });
+in {
+  imports = [
+    # Import the NixOS module from your fetched input
+    nvf.nixosModules.nvf
+  ];
+
+  # Once the module is imported, you may use `programs.nvf` as exposed by the
+  # NixOS module.
+  programs.nvf.enable = true;
+}
+```
+
+[npins]: https://github.com/andir/npins
+[niv]: https://github.com/nmattia/niv
+
+::: {.tip}
+
+Nix2 does not have a builtin lockfile mechanism like flakes. As such you must
+manually update the URL and hash for your input. This is annoying to deal with,
+and most users choose to defer this task to projects such as [npins] or [niv].
+If you are new to NixOS, I encourage you to look into Flakes and see if they fit
+your use case. Alternatively, look into the aforementioned projects for more
+convenient dependency management mechanisms.
+
+:::

docs/manual/try-it-out.md

@@ -5,19 +5,20 @@ installing it to your machine. Below are the commands you may run to try out
 different configurations provided by this flake. As of v0.5, two specialized
 configurations are provided:
 
-- **Nix** - Nix language server + simple utility plugins
+- **Nix** (`packages.nix`) - Nix language server + simple utility plugins
-- **Maximal** - Variable language servers + utility and decorative plugins
+- **Maximal** (`packages.maximal`) - Variable language servers + utility and
+  decorative plugins
 
 You may try out any of the provided configurations using the `nix run` command
 on a system where Nix is installed.
 
-```bash
+```sh
 $ cachix use nvf                   # Optional: it'll save you CPU resources and time
-$ nix run github:notashelf/nvf#nix # will run the default minimal configuration
+$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
 ```
 
-Do keep in mind that this is **susceptible to garbage collection** meaning it
+Do keep in mind that this is **susceptible to garbage collection** meaning that
-will be removed from your Nix store once you garbage collect.
+the built outputs will be removed from your Nix store once you garbage collect.
 
 ## Using Prebuilt Configs {#sec-using-prebuilt-configs}
 
@@ -65,6 +66,7 @@ companion or fun plugins.
 ::: {.warning}
 
 Running the maximal config will download _a lot_ of packages as it is
-downloading language servers, formatters, and more.
+downloading language servers, formatters, and more. If CPU time and bandwidth
+are concerns, please use the default package instead.
 
 :::