docs/manual: add more details to existing documentation pages

This commit is contained in:
raf 2023-10-03 22:06:26 +03:00
parent 96c568f99b
commit 0c848869cf
No known key found for this signature in database
GPG key ID: 02D1DD3FA08B6B29
7 changed files with 131 additions and 39 deletions

View file

@ -1,6 +1,6 @@
{
pkgs,
lib ? import ../lib/stdlib-extended.nix pkgs.lib,
lib,
nmdSrc,
}: let
nmd = import nmdSrc {

View file

@ -18,8 +18,8 @@
<xi:include href="manual/try-it-out.xml"/>
<xi:include href="manual/default-configs.xml"/>
<xi:include href="manual/custom-configs.xml"/>
<xi:include href="manual/custom-plugins.xml"/>
<xi:include href="manual/custom-package.xml"/>
<xi:include href="manual/custom-plugins.xml"/>
<xi:include href="manual/home-manager.xml"/>
<xi:include href="manual/languages.xml"/>
<xi:include href="manual/hacking.xml"/>

View file

@ -1,7 +1,8 @@
[[ch-custom-configuration]]
== Custom Configuration
Custom configuration is done with the `neovimConfiguration` function. It takes in the configuration as a module. The output of the configuration function is an attrset.
Custom configuration is done with the `neovimConfiguration` while using the flake as a standalone package.
It takes in the configuration as a module. The output of the configuration function is an attrset.
[source,nix]
----
@ -40,8 +41,28 @@ The following is an example of a barebones vim configuration with the default th
inherit pkgs;
};
in {
# this will make the package available as a flake input
packages.${system}.neovim = customNeovim.neovim;
# this is an example nixosConfiguration using the built neovim package
nixosConfigurations = {
yourHostName = nixpkgs.lib.nixosSystem {
# ...
modules = [
./configuration.nix # or whatever your configuration is
# this will make wrapped neovim available in your system packages
{environment.systemPackages = [customNeovim.neovim];}
];
# ...
};
};
};
}
----
Your built neovim configuration can be exposed as a flake output, or be added to your system packages to make
it available across your system. You may also consider passing the flake output to home-manager to make it available
to a specific user *without* using the home-manager module.

View file

@ -4,7 +4,7 @@
You can use custom plugins, before they are implemented in the flake.
To add a plugin, you need to add it to your config's `config.vim.startPlugins` array.
[[sec-new-method]]
=== New Method
As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
@ -22,7 +22,7 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
}
'';
};
harpoon = {
package = harpoon;
setup = "require('harpoon').setup {}";
@ -32,8 +32,10 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
}
----
[[sec-old-method]]
=== Old Method
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load orderof the plugins is determined by DAGs.
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load order
of the plugins is determined by DAGs.
[source,nix]
----
@ -50,16 +52,23 @@ Users who have not yet updated to 0.5, or prefer a more hands-on approach may us
}
----
However, just making the plugin available might not be enough. In that case, you can write custom vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
However, just making the plugin available might not be enough. In that case, you can write custom vimscript
or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
These options are attribute sets, and you need to give the configuration you're adding some name, like this:
[source,nix]
----
{
# this will create an "aquarium" section in your init.vim with the contents of your custom config
# which will be *appended* to the rest of your configuration, inside your init.vim
config.vim.configRC.aquarium = "colorscheme aquiarum";
}
----
Note: If your configuration needs to be put in a specific place in the config, you can use functions from `inputs.neovim-flake.lib.nvim.dag` to order it. Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix.
Note: If your configuration needs to be put in a specific place in the config, you can use functions from
`inputs.neovim-flake.lib.nvim.dag` to order it.
Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
the DAG system.
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue with your findings so that we can make it available for everyone easily.
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
with your findings so that we can make it available for everyone easily.

View file

@ -1,7 +1,10 @@
[[ch-hm-module]]
== Home Manager
The Home Manager module allows us to customize the different `vim` options. To use it, we first add the input flake.
The Home Manager module allows us to customize the different `vim` options from inside the home-manager configuration
and it is the preferred way of configuring neovim-flake, both on NixOS and non-NixOS systems.
To use it, we first add the input flake.
[source,nix]
----
@ -10,20 +13,49 @@ The Home Manager module allows us to customize the different `vim` options. To u
url = github:notashelf/neovim-flake;
# you can override input nixpkgs
inputs.nixpkgs.follows = "nixpkgs";
# you can also override individual plugins
# i.e inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- obsidian nvim needs to be in your inputs
};
}
----
Followed by importing the HM module.
Followed by importing the home-manager module somewhere in your configuration.
[source,nix]
----
{
imports = [ neovim-flake.homeManagerModules.default ];
# assuming neovim-flake is in your inputs and inputs is in the argset
imports = [ inputs.neovim-flake.homeManagerModules.default ];
}
----
Then we should be able to use the given module. E.g.
An example installation for standalone home-manager would look like this:
[source,nix]
----
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
stylix.url = "github:notashelf/neovim-flake";
};
outputs = { nixpkgs, home-manager, neovim-flake ... }: let
system = "x86_64-linux"; in {
# ↓ this is the home-manager output in the flake schema
homeConfigurations."yourUsername»" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
neovim-flake.homeManagerModules.default # <- this imports the home-manager module that provides the options
./home.nix # your home-manager configuration, probably where you will want to add programs.neovim-flake options
];
};
};
}
----
Once the module is imported, we will be able to define the following options (and much more) from inside the
home-manager configuration.
[source,nix]
----
@ -31,7 +63,8 @@ Then we should be able to use the given module. E.g.
programs.neovim-flake = {
enable = true;
# your settings need to go into the settings attrset
# your settings need to go into the settings attribute set
# most settings are documented in the appendix
settings = {
vim.viAlias = false;
vim.vimAlias = true;
@ -43,4 +76,10 @@ Then we should be able to use the given module. E.g.
}
----
[NOTE]
====
You may find all avaliable options in the https://notashelf.github.io/neovim-flake/options[appendix]
====

View file

@ -15,21 +15,25 @@ Language specific support means there is a combination of language specific plug
* SQL: <<opt-vim.languages.sql.enable>>
* Dart: <<opt-vim.languages.dart.enable>>
* Go: <<opt-vim.languages.go.enable>>
* Lua: <<opt-vim.languages.lua.enable>>
Adding support for more languages, and improving support for existing ones are great places where you can contribute with a PR.
Adding support for more languages, and improving support for existing ones are great places
where you can contribute with a PR.
=== LSP Custom Packages/Command
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide the command to launch the language server, as a list of strings.
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
the command to launch the language server, as a list of strings.
You can use this to skip automatic installation of a language server, and instead use the one found in your `$PATH` during runtime, for example:
You can use this to skip automatic installation of a language server, and instead
use the one found in your `$PATH` during runtime, for example:
[source,nix]
----
vim.languages.java = {
lsp = {
enable = true;
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
};
lsp = {
enable = true;
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
};
}
----

View file

@ -1,34 +1,53 @@
[[ch-try-it-out]]
== Try it out
Thanks to the portability of Nix, you can try out neovim-flake without actually 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, three
configurations are provided:
* Nix
* Tidal
* Maximal
You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
[source,console]
----
$ cachix use neovim-flake # Optional: it'll save you CPU resources and time
$ nix run github:notashelf/neovim-flake # will run the default configuration
$ nix run github:notashelf/neovim-flake#nix # will run the default minimal configuration
----
Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
once you garbage collect. If you wish to install neovim-flake, please take a look at
<<ch-custom-configuration,custom-configuration>> or <<ch-hm-module,home-manager>> sections for installation
instructions.
=== Nix
By default LSP support for Nix is enabled alongside all complementary Neovim plugins. By running `nix run .`, which is the default package,
you will build Neovim with this config.
=== Tidal
Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
=== Maximal
Maximal is the ultimate configuration that will enable basically everything. Keep in mind, however, that this will pull a lot of dependencies.
You are strongly recommended to use the binary cache if you would like to try the Maximal configuration.
[[sec-using-prebuild-configs]]
=== Using Prebuilt Configs
[source,console]
----
$ nix run github:notashelf/neovim-flake#nix
$ nix run github:notashelf/neovim-flake#nix
$ nix run github:notashelf/neovim-flake#tidal
$ nix run github:notashelf/neovim-flake#maximal
----
[[sec-available-configs]]
=== Available Configs
==== Nix
`Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
By running `nix run .`, which is the default package, you will build Neovim with this config.
==== Tidal
Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
==== Maximal
`Maximal` is the ultimate configuration that will enable support for more commonly used language as well as additional
complementary plugins. Keep in mind, however, that this will pull a lot of dependencies.
You are *strongly* recommended to use the binary cache if you would like to try the Maximal configuration.