From 6645abb6e87d88d126125f267c9c22bdb7ee166a Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 4 Nov 2024 17:00:28 +0300 Subject: [PATCH 01/32] flake: improve deprecation messages for old `neovim-flake` modules' --- flake.nix | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/flake.nix b/flake.nix index 4e417e7f..1123432e 100644 --- a/flake.nix +++ b/flake.nix @@ -31,29 +31,25 @@ }; homeManagerModules = { + nvf = import ./flake/modules/home-manager.nix self.packages lib; + default = self.homeManagerModules.nvf; neovim-flake = lib.warn '' - homeManagerModules.neovim-flake has been deprecated. - Plese use the homeManagerModules.nvf instead + 'homeManagerModules.neovim-flake' has been deprecated, and will be removed + in a future release. Please use 'homeManagerModules.nvf' instead. '' self.homeManagerModules.nvf; - - nvf = import ./flake/modules/home-manager.nix self.packages lib; - - default = self.homeManagerModules.nvf; }; nixosModules = { + nvf = import ./flake/modules/nixos.nix self.packages lib; + default = self.nixosModules.nvf; neovim-flake = lib.warn '' - nixosModules.neovim-flake has been deprecated. - Please use the nixosModules.nvf instead + 'nixosModules.neovim-flake' has been deprecated, and will be removed + in a future release. Please use 'nixosModules.nvf' instead. '' self.nixosModules.nvf; - - nvf = import ./flake/modules/nixos.nix self.packages lib; - - default = self.nixosModules.nvf; }; }; From 94d04ba0dff8b5d7cf6a028be791a6bc66ca2e7c Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 4 Nov 2024 17:23:18 +0300 Subject: [PATCH 02/32] docs: clean up project README --- .github/README.md | 72 ++++++++++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/.github/README.md b/.github/README.md index 531d062b..029f2fc8 100644 --- a/.github/README.md +++ b/.github/README.md @@ -48,7 +48,7 @@ [Documentation]: #documentation [Help]: #help [Contribute]: #contributing -[FAQ]: #faq +[FAQ]: #frequently-asked-questions [Credits]: #credits **[
 Features
][Features]** @@ -56,7 +56,7 @@ **[
 Documentation 
][Documentation]** **[
 Help 
][Help]** **[
 Contribute 
][Contribute]** -**[
 FAQ 
][Faq]** **[
 Credits 
][Credits]** +**[
 FAQ 
][FAQ]** **[
 Credits 
][Credits]**

@@ -64,12 +64,21 @@ ## Features +[standalone]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-installation +[NixOS module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-nixos +[Home-Manager module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-hm + +- **Simple**: One language to rule them all! Use Nix to configure everything, + with additional Lua Support - **Reproducible**: Your configuration will behave the same _anywhere_. No surprises, promise! - **Portable**: nvf depends _solely_ on your Nix store, and nothing else. No more global binaries! Works on all platforms, without hassle. + - Options to install [standalone], [NixOS module] or [Home-Manager module]. - **Customizable**: There are _almost no defaults_ to annoy you. nvf is fully customizable through the Nix module system. +- Not comfortable with a full-nix config or want to bring your Lua config? You + can do just that, no unnecessary restrictions. - **Well-documented**: Documentation is priority. You will _never_ face undocumented, obscure behaviour. - **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and @@ -120,7 +129,9 @@ instructions. ## Documentation -The _recommended_ way of installing **nvf** is using either the NixOS or the +### Installation + +The _recommended_ way of installing nvf is using either the NixOS or the Home-Manager module, though it is completely possible and no less supported to install **nvf** as a standalone package, or a flake output. @@ -138,11 +149,13 @@ Please create an issue on the [issue tracker] if you find the documentation lacking or confusing. Any improvements to the documentation through pull requests are also welcome, and appreciated. -## Help +## Getting Help -You can create an issue on the [issue tracker] to ask questions or report bugs. -I am not yet on spaces like matrix or IRC, so please use the issue tracker for -now. +If you are confused, stuck or would like to ask a simple question; you may +create an issue on the [issue tracker] to ask questions or report bugs. + +We are not not yet on spaces like matrix or IRC, so please use the issue tracker +for now. ## Contributing @@ -152,7 +165,7 @@ submitting a pull request. You can also create an issue on the [issue tracker] before submitting a pull request if you would like to discuss a feature or bug fix. -## FAQ +## Frequently Asked Questions [appropriate issue template]: https://github.com/NotAShelf/nvf/issues/new/choose [list of branches]: https://github.com/NotAShelf/nvf/branches @@ -160,13 +173,15 @@ fix. **Q**: What platforms are supported?
**A**: nvf actively supports Linux and Darwin platforms using standalone -Nix, NixOS or Home-Manager. Please take a look at the +Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] for available +installation instructions. **Q**: Can you add _X_?
**A**: Maybe! It is not one of our goals to support each and every Neovim plugin, however, I am always open to new modules and plugin setup additions to **nvf**. Use the [appropriate issue template] and I will consider a module -addition. As mentioned before, PRs adding new features are also welcome. +addition. As mentioned before, pull requests to add new features are also +welcome. **Q**: A plugin I need is not available in **nvf**. What to do?
**A**: **nvf** exposes several APIs for you to be able to add your own @@ -185,22 +200,26 @@ better prepare to breaking changes. ### Contributors -Special, heart-felt thanks to +[mnw]: https://github.com/gerg-l/mnw -- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts -- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to - work +nvf would not be what it is today without the awesome people below. Special, +heart-felt thanks to + +- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts and + invaluable Nix assistance. +- [@FlafyDev](https://github.com/FlafyDev) - For getting home-manager module to + work and Nix assistance. - [@n3oney](https://github.com/n3oney) - For making custom keybinds finally - possible + possible, and other module additions. - [@horriblename](https://github.com/horriblename) - For actively implementing - planned features and quality of life updates + planned features and quality of life updates. - [@Yavko](https://github.com/Yavko) - For the amazing **nvf** logo - [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I - could not -- [@Diniamo](https://github.com/Diniamo) - For actively submitting PRs, pull - requests and overall assistence -- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, mnw and - occasional code improvements + could not. +- [@Diniamo](https://github.com/Diniamo) - For actively submitting pull + requests, issues and assistance with maintenance of nvf. +- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, [mnw], + and occasional code improvements. and everyone who has submitted issues or pull requests! @@ -214,7 +233,7 @@ including: is originally based on. - [@sioodmy's](https://github.com/sioodmy) [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design - choices. + choices for UI and plugin defaults. - [@wiltaylor's](https://github.com/wiltaylor) [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and design ideas. @@ -229,10 +248,11 @@ recommend checking their work out. ## License Following the license of the -[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), **nvf** -has been made available under the [**MIT License**](LICENSE). However, all -assets and documentation are published under the -[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE). +[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), nvf has +been made available under the [**MIT License**](LICENSE). However, all assets +and documentation are published under the +[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE) +under explicit permission by the artist.
Yes, this includes the logo work too. Stop taking artwork that is not yours!
From 7c8dc07824bcaa0f7ff465c23e1fc5db45588025 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 4 Nov 2024 17:38:45 +0300 Subject: [PATCH 03/32] docs: fix typo in standalone installation pages --- docs/manual/installation/standalone/home-manager.md | 2 +- docs/manual/installation/standalone/nixos.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manual/installation/standalone/home-manager.md b/docs/manual/installation/standalone/home-manager.md index db1ae632..1f5d55ce 100644 --- a/docs/manual/installation/standalone/home-manager.md +++ b/docs/manual/installation/standalone/home-manager.md @@ -1,6 +1,6 @@ # Standalone Installation on Home-Manager {#ch-standalone-hm} -Your built Neoevim configuration can be exposed as a flake output to make it +Your built Neovim configuration can be exposed as a flake output to make it easier to share across machines, repositories and so on. Or it can be added to your system packages to make it available across your system. diff --git a/docs/manual/installation/standalone/nixos.md b/docs/manual/installation/standalone/nixos.md index 2e6343a1..33235ac7 100644 --- a/docs/manual/installation/standalone/nixos.md +++ b/docs/manual/installation/standalone/nixos.md @@ -1,6 +1,6 @@ # Standalone Installation on NixOS {#ch-standalone-nixos} -Your built Neoevim configuration can be exposed as a flake output to make it +Your built Neovim configuration can be exposed as a flake output to make it easier to share across machines, repositories and so on. Or it can be added to your system packages to make it available across your system. From 5b54f6d5f5b937609a11274311ac77ea25375b51 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 4 Nov 2024 17:39:10 +0300 Subject: [PATCH 04/32] docs/installation: add standalone flake example --- .../installation/custom-configuration.md | 54 +++++++++++++++++-- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/docs/manual/installation/custom-configuration.md b/docs/manual/installation/custom-configuration.md index 408b0399..64ae64ee 100644 --- a/docs/manual/installation/custom-configuration.md +++ b/docs/manual/installation/custom-configuration.md @@ -1,8 +1,9 @@ # Standalone Installation {#ch-standalone-installation} -It is possible to install **nvf** without depending on NixOS or home-manager as the parent -module system, using the `neovimConfiguration` function exposed by **nvf** extended library. -It takes in the configuration as a module, and returns an attribute set as a result. +It is possible to install nvf without depending on NixOS or Home-Manager as the +parent module system, using the `neovimConfiguration` function exposed in the +extended library. This function will take `modules` and `extraSpecialArgs` as +arguments, and return the following schema as a result. ```nix { @@ -13,6 +14,53 @@ It takes in the configuration as a module, and returns an attribute set as a res } ``` +An example flake that exposes your custom Neovim configuration might look like + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + nvf.url = "github:notashelf/nvf"; + }; + + outputs = { + self, + nixpkgs, + ... + } @ inputs: { + packages."x86_64-linux" = let + neovimConfigured = (inputs.nvf.lib.neovimConfiguration { + inherit (nixpkgs.legacyPackages."x86_64-linux") pkgs; + modules = [{ + config.vim = { + # Enable custom theming options + theme.enable = true; + + # Enable Treesitter + tree-sitter.enable = true; + + # Other options will go here. Refer to the config + # reference in Appendix B of the nvf manual. + # ... + }; + }]; + }); + in { + # Set the default package to the wrapped instance of Neovim. + # This will allow running your Neovim configuration with + # `nix run` and in addition, sharing your configuration with + # other users in case your repository is public. + default = neovimConfigured.neovim; + }; + }; +} +``` + + + +The next two chapters will detail specific usage of standalone nvf +configurations on NixOS and Home-Manager. + ```{=include=} chapters standalone/nixos.md standalone/home-manager.md From b2600885c8f025ee768f2af3c7ebbd9e21b5bf00 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 4 Nov 2024 17:39:23 +0300 Subject: [PATCH 05/32] docs: add preface to modules chapter --- docs/manual/installation/modules.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/manual/installation/modules.md b/docs/manual/installation/modules.md index d8462e9d..f78046de 100644 --- a/docs/manual/installation/modules.md +++ b/docs/manual/installation/modules.md @@ -1,5 +1,9 @@ # Module Installation {#ch-module-installation} +The below chapters will describe installing nvf as NixOS and Home-Manager +modules. Note that those methods are mutually exclusive, and will likely cause +path collisions if used simultaneously. + ```{=include=} chapters modules/nixos.md modules/home-manager.md From c382bb02eb6e8309ae59ea11209c5ace9d635c85 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 10:57:59 +0300 Subject: [PATCH 06/32] docs/custom-plugins: better wording and edge cases in legacy-method.md --- .../configuring/custom-plugins/legacy-method.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/manual/configuring/custom-plugins/legacy-method.md b/docs/manual/configuring/custom-plugins/legacy-method.md index 0a6b3775..b2bddf43 100644 --- a/docs/manual/configuring/custom-plugins/legacy-method.md +++ b/docs/manual/configuring/custom-plugins/legacy-method.md @@ -1,6 +1,6 @@ # Legacy Method {#sec-legacy-method} -Prior to version 0.5, the method of adding new plugins was adding the plugin +Prior to version v0.5, the method of adding new plugins was adding the plugin package to `vim.startPlugins` and add its configuration as a DAG under one of `vim.configRC` or `vim.luaConfigRC`. 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 @@ -8,13 +8,14 @@ the plugins is determined by DAGs. ## Adding plugins {#sec-adding-plugins} -To add a plugin to **nvf**'s runtime, you may add it +To add a plugin not available in nvf as a module to your configuration, you may +add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at +runtime. ```nix {pkgs, ...}: { - # add a package from nixpkgs to startPlugins - vim.startPlugins = [ - pkgs.vimPlugins.aerial-nvim ]; + # Add a Neovim plugin from Nixpkgs to the runtime. + vim.startPlugins = [pkgs.vimPlugins.aerial-nvim]; } ``` @@ -23,7 +24,9 @@ provide configuration as a DAG using the **nvf** extended library. ```nix {inputs, ...}: let - # assuming you have an input called nvf pointing at the nvf repository + # This assumes you have an input called 'nvf' in your flake inputs + # and 'inputs' in your specialArgs. In the case you have passed 'nvf' + # to specialArgs, the 'inputs' prefix may be omitted. inherit (inputs.nvf.lib.nvim.dag) entryAnywhere; in { vim.luaConfigRC.aerial-nvim= entryAnywhere '' From d0ae648119fe30f763620077de46dca4eaa58ba0 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 10:58:40 +0300 Subject: [PATCH 07/32] docs/custom-plugins: improve wording for DAG; link to local docs --- .../configuring/custom-plugins/configuring.md | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/manual/configuring/custom-plugins/configuring.md b/docs/manual/configuring/custom-plugins/configuring.md index 80ef03a4..c0935f03 100644 --- a/docs/manual/configuring/custom-plugins/configuring.md +++ b/docs/manual/configuring/custom-plugins/configuring.md @@ -1,12 +1,13 @@ # Configuring {#sec-configuring-plugins} -Just making the plugin to your Neovim configuration available might not always be enough. In that -case, you can write custom lua config using either `config.vim.lazy.plugins.*.setupOpts` -`config.vim.extraPlugins.*.setup` or `config.vim.luaConfigRC`. +Just making the plugin to your Neovim configuration available might not always +be enough. In that case, you can write custom lua config using either +`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or +`config.vim.luaConfigRC`. -The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule` and `setupOpt` can -be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise, the `before` and -`after` hooks should do what you need. +The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule` +and `setupOpt` can be used if the plugin uses a `require('module').setup(...)` +pattern. Otherwise, the `before` and `after` hooks should do what you need. ```nix { @@ -24,10 +25,11 @@ be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise, } ``` -The second option uses an attribute set, which maps DAG section names to a custom type, which has -the fields `package`, `after`, `setup`. They allow you to set the package of the plugin, the -sections its setup code should be after (note that the `extraPlugins` option has its own DAG -scope), and the its setup code respectively. For example: +The second option uses an attribute set, which maps DAG section names to a +custom type, which has the fields `package`, `after`, `setup`. They allow you to +set the package of the plugin, the sections its setup code should be after (note +that the `extraPlugins` option has its own DAG scope), and the its setup code +respectively. For example: ```nix config.vim.extraPlugins = with pkgs.vimPlugins; { @@ -56,13 +58,17 @@ For example: } ``` -:::{.note} -If your configuration needs to be put in a specific place in the config, you -can use functions from `inputs.nvf.lib.nvim.dag` to order it. Refer to -https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix + + +::: {.note} +One of the greatest strengths of nvf is the ability to order +snippets of configuration via the DAG system. It will allow specifying positions +of individual sections of configuration as needed. nvf provides helper functions +in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may +use. + +Please refer to the [DAG section](/index.xhtml#ch-dag-entries) in the nvf manual to find out more about the DAG system. ::: -If you successfully made your plugin work, please feel free to create a PR to -add it to **nvf** or open an issue with your findings so that we can make it -available for everyone easily. + From 4156ecfb21a46722cc456fca92fa45a7dae22723 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:06:07 +0300 Subject: [PATCH 08/32] docs/try-it-out: correct number of available configs; fix typos --- docs/manual/try-it-out.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/manual/try-it-out.md b/docs/manual/try-it-out.md index bd8c69bb..8244c2b7 100644 --- a/docs/manual/try-it-out.md +++ b/docs/manual/try-it-out.md @@ -1,25 +1,27 @@ # Try it out {#ch-try-it-out} -Thanks to the portability of Nix, you can try out nvf 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 +Thanks to the portability of Nix, you can try out nvf 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, two specialized configurations are provided: -- Nix -- Maximal +- **Nix** - Nix language server + simple utility plugins +- **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. +You may try out any of the provided configurations using the `nix run` command +on a system where Nix is installed. -```console +```bash $ cachix use nvf # Optional: it'll save you CPU resources and time $ 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 will be removed from your Nix store -once you garbage collect. +Do keep in mind that this is **susceptible to garbage collection** meaning it +will be removed from your Nix store once you garbage collect. -## Using Prebuilt Configs {#sec-using-prebuild-configs} +## Using Prebuilt Configs {#sec-using-prebuilt-configs} -```console +```bash $ nix run github:notashelf/nvf#nix $ nix run github:notashelf/nvf#maximal ``` @@ -28,12 +30,19 @@ $ nix run github:notashelf/nvf#maximal #### Nix {#sec-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. +`Nix` configuration by default provides LSP/diagnostic support for Nix alongside +a set of visual and functional plugins. By running `nix run .#`, which is the +default package, you will build Neovim with this config. #### Maximal {#sec-configs-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. +`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. +::: {.tip} + +You are _strongly_ recommended to use the binary cache if you would like to try +the Maximal configuration. + +::: From ce6799c9d8d80eacd5935a4830bff64398b2e4a6 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:07:02 +0300 Subject: [PATCH 09/32] docs/plugins: rename to 'quirks' to be more general --- docs/manual/plugins.md | 16 ---------------- docs/manual/quirks.md | 13 +++++++++++++ docs/manual/{plugins => quirks}/nodejs.md | 16 +++++++++++----- 3 files changed, 24 insertions(+), 21 deletions(-) delete mode 100644 docs/manual/plugins.md create mode 100644 docs/manual/quirks.md rename docs/manual/{plugins => quirks}/nodejs.md (58%) diff --git a/docs/manual/plugins.md b/docs/manual/plugins.md deleted file mode 100644 index fa464d18..00000000 --- a/docs/manual/plugins.md +++ /dev/null @@ -1,16 +0,0 @@ -# Plugin specific quirks {#ch-plugins} - -At times, certain plugins refuse to play nicely. Be it as a result of generating -lua from Nix, or the state of packaging. This page shall list any plugins that -are known to misbehave, and potential workarounds. - -```{=include=} chapters -plugins/nodejs.md -``` - diff --git a/docs/manual/quirks.md b/docs/manual/quirks.md new file mode 100644 index 00000000..553d6cf3 --- /dev/null +++ b/docs/manual/quirks.md @@ -0,0 +1,13 @@ +# Known Issues and Quirks {#ch-known-issues-quirks} + +At times, certain plugins and modules may refuse to play nicely with your setup, +be it a result of generating Lua from Nix, or the state of packaging. This page, +in turn, will list any known modules or plugins that are known to misbehave, and +possible workarounds that you may apply. + + + +```{=include=} chapters +quirks/nodejs.md +``` diff --git a/docs/manual/plugins/nodejs.md b/docs/manual/quirks/nodejs.md similarity index 58% rename from docs/manual/plugins/nodejs.md rename to docs/manual/quirks/nodejs.md index 36b4c79c..d2fb46b7 100644 --- a/docs/manual/plugins/nodejs.md +++ b/docs/manual/quirks/nodejs.md @@ -1,16 +1,22 @@ -# NodeJS {#ch-plugins-nodejs} +# NodeJS {#ch-quirks-nodejs} ## eslint-plugin-prettier {#sec-eslint-plugin-prettier} -When working with NodeJS, everything works as expected, but some projects have settings that can fool nvf. +When working with NodeJS, everything works as expected, but some projects have +settings that can fool nvf. -If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar is included, you might get a situation where your eslint configuration diagnoses your formatting according to its own config (usually `.eslintrc.js`). +If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar +is included, you might get a situation where your eslint configuration diagnoses +your formatting according to its own config (usually `.eslintrc.js`). The issue there is your formatting is made via prettierd. -This results in auto-formating relying on your prettier config, while your eslint config diagnoses formatting [which it's not supposed to](https://prettier.io/docs/en/comparison.html)) +This results in auto-formating relying on your prettier config, while your +eslint config diagnoses formatting +[which it's not supposed to](https://prettier.io/docs/en/comparison.html)) -In the end, you get discrepancies between what your editor does and what it wants. +In the end, you get discrepancies between what your editor does and what it +wants. Solutions are: From 344348512ecded6cbd29249816584594f8a90a52 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:07:22 +0300 Subject: [PATCH 10/32] docs/preface: include project description in the preface --- docs/manual/preface.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/manual/preface.md b/docs/manual/preface.md index 26e30704..ce3e42e6 100644 --- a/docs/manual/preface.md +++ b/docs/manual/preface.md @@ -1,7 +1,20 @@ # Preface {#ch-preface} -If you noticed a bug caused by **nvf** then please consider reporting it over -[the issue tracker](https://github.com/notashelf/nvf/issues). +## What is nvf {#sec-what-is-it} -Bugfixes, feature additions and upstreamed changes from your local configurations -are always welcome in the [the pull requests tab](https://github.com/notashelf/nvf/pulls). +nvf is a highly modular, configurable, extensible and easy to use Neovim +configuration in Nix. Designed for flexibility and ease of use, nvf allows you +to easily configure your fully featured Neovim instance with a few lines of Nix. + +## Bugs & Suggestions {#sec-bugs-suggestions} + +[issue tracker]: https://github.com/notashelf/nvf/issues +[discussions tab]: https://github.com/notashelf/nvf/discussions +[pull requests tab]: https://github.com/notashelf/nvf/pulls + +If you notice any issues with nvf, or this documentation, then please consider +reporting them over at the [issue tracker]. Issues tab, in addition to the +[discussions tab] is a good place as any to request new features. + +You may also consider submitting bugfixes, feature additions and upstreamed +changes that you think are critical over at the [pull requests tab]. From eaeb99539bbfa3eb53ecfa0993a46637b1ab1fe7 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:08:53 +0300 Subject: [PATCH 11/32] docs: use the correct path for quirks.md --- docs/manual/manual.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manual/manual.md b/docs/manual/manual.md index 905a7242..fd7ddcd9 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -17,8 +17,8 @@ configuring.md hacking.md ``` -```{=include=} appendix html:into-file=//plugins.html -plugins.md +```{=include=} appendix html:into-file=//quirks.html +quirks.md ``` ```{=include=} appendix html:into-file=//options.html From 3b27c00268e8d600e06265fa1809a7dff69c7424 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:16:53 +0300 Subject: [PATCH 12/32] docs/options: include warning about option prefix --- docs/manual/options.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/manual/options.md b/docs/manual/options.md index 748e3180..3b70484f 100644 --- a/docs/manual/options.md +++ b/docs/manual/options.md @@ -1,8 +1,14 @@ # Neovim Flake Configuration Options {#ch-options} -Below are the options provided by nvf provided in no particular order. -They may include useful comments and warnings, or examples on how a module option -is meant to be used. +Below are the module options provided by nvf, in no particular order. Most +options will include useful comments, warnings or setup tips on how a module +option is meant to be used as well as examples in complex cases. + + ```{=include=} options id-prefix: opt- From 41931ea87a1885a307b0cb6e55d3a6ae4e34e998 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:17:24 +0300 Subject: [PATCH 13/32] docs/installation: un-linline section link --- docs/manual/installation.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/manual/installation.md b/docs/manual/installation.md index afe60d16..33dd8979 100644 --- a/docs/manual/installation.md +++ b/docs/manual/installation.md @@ -1,9 +1,12 @@ # Installing nvf {#ch-installation} +[module installation section]: #ch-module-installation + There are multiple ways of installing nvf on your system. You may either choose -the standalone installation method, which does not depend on a module system and may -be done on any system that has the Nix package manager or the appropriate modules -for NixOS and home-manager as described in the [module installation section](#ch-module-installation) +the standalone installation method, which does not depend on a module system and +may be done on any system that has the Nix package manager or the appropriate +modules for NixOS and home-manager as described in the +[module installation section]. ```{=include=} chapters installation/custom-configuration.md From a8ebd8972bb1d89b9b47b118dcf5adff337da0e9 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:17:51 +0300 Subject: [PATCH 14/32] docs/hacking: make preface more readable & friendly --- docs/manual/hacking.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/manual/hacking.md b/docs/manual/hacking.md index 394022ba..6ff01fc6 100644 --- a/docs/manual/hacking.md +++ b/docs/manual/hacking.md @@ -1,16 +1,25 @@ # Hacking nvf {#ch-hacking} -**nvf** is designed for developers as much as it is for the end user. I would like any potential contributor -to be able to propagate their desired changes into the repository without the extra effort. As such, below are guides -(and guidelines) to streamline the contribution process and ensure that your valuable input seamlessly integrates -into **nvf**'s development without leaving question marks in your head. +[open issues]: https://github.com/notashelf/nvf/issues +[new issue]: https://github.com/notashelf/nvf/issues/new -This section is mainly directed towards those who wish to contribute code into **nvf**. If you wish to instead -report a bug or discuss a potential feature implementation, first look among the -already [open issues](https://github.com/notashelf/nvf/issues) and if no matching issue exists you may open -a [new issue](https://github.com/notashelf/nvf/issues/new) and describe your problem/request. While creating an -issue, please try to include as much information as you can, ideally also include relevant context in which an issue -occurs or a feature should be implemented. +nvf is designed for the developer as much as it is designed for the end-user. We +would like for any contributor to be able to propagate their changes, or add new +features to the project with minimum possible friction. As such, below are the +guides and guidelines written to streamline the contribution process and to +ensure that your valuable input integrates into nvf's development as seamlessly +as possible without leaving any question marks in your head. + +This section is directed mainly towards those who wish to contribute code into +the project. If you instead wish to report a bug, or discuss a potential new +feature implementation (which you do not wish to implement yourself) first look +among the already [open issues] and if no matching issue exists you may open a +[new issue] and describe your problem/request. + +While creating an issue, please try to include as much information as you can, +ideally also include relevant context in which an issue occurs or a feature +should be implemented. If you wish to make a contribution, but feel stuck - +please do not be afraid to submit a pull request, we will help you get it in. ```{=include=} sections hacking/getting-started.md From 1e9f5d09a73aa42daced8696cfa2ab5f45a0b22b Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 15:45:03 +0300 Subject: [PATCH 15/32] docs/installation: connect custom-configuration section to the module chapters better --- docs/manual/installation/custom-configuration.md | 6 ++++-- docs/manual/installation/modules/home-manager.md | 6 ++++-- docs/manual/installation/modules/nixos.md | 6 ++++-- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/manual/installation/custom-configuration.md b/docs/manual/installation/custom-configuration.md index 64ae64ee..b6c27163 100644 --- a/docs/manual/installation/custom-configuration.md +++ b/docs/manual/installation/custom-configuration.md @@ -58,8 +58,10 @@ An example flake that exposes your custom Neovim configuration might look like -The next two chapters will detail specific usage of standalone nvf -configurations on NixOS and Home-Manager. +The above setup will allow to set up nvf as a standalone flake, which you can +build independently from your system configuration while also possibly sharing +it with others. The next two chapters will detail specific usage of such a setup +for a package output in the context of NixOS or Home-Manager installation. ```{=include=} chapters standalone/nixos.md diff --git a/docs/manual/installation/modules/home-manager.md b/docs/manual/installation/modules/home-manager.md index 6764f797..a2170159 100644 --- a/docs/manual/installation/modules/home-manager.md +++ b/docs/manual/installation/modules/home-manager.md @@ -77,7 +77,9 @@ configure **nvf**. ``` ::: {.note} + **nvf** exposes a lot of options, most of which are not referenced in the -installation sections of the manual. You may find all avaliable options -in the [appendix](https://notashelf.github.io/nvf/options) +installation sections of the manual. You may find all available options in the +[appendix](https://notashelf.github.io/nvf/options) + ::: diff --git a/docs/manual/installation/modules/nixos.md b/docs/manual/installation/modules/nixos.md index 9cbc1447..d8be2035 100644 --- a/docs/manual/installation/modules/nixos.md +++ b/docs/manual/installation/modules/nixos.md @@ -76,7 +76,9 @@ configure **nvf**. ``` ::: {.note} + **nvf** exposes a lot of options, most of which are not referenced in the -installation sections of the manual. You may find all avaliable options -in the [appendix](https://notashelf.github.io/nvf/options) +installation sections of the manual. You may find all available options in the +[appendix](https://notashelf.github.io/nvf/options) + ::: From cb10266dce8c41499491350d859797474adbcaec Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 7 Nov 2024 16:11:53 +0300 Subject: [PATCH 16/32] docs: add anchors to individual headers Taken from Nixpkgs manual derivation, neat. --- docs/manual.nix | 108 +++++++++++++++++++------------ docs/static/script/anchor-min.js | 10 +++ docs/static/script/anchor-use.js | 4 ++ 3 files changed, 79 insertions(+), 43 deletions(-) create mode 100644 docs/static/script/anchor-min.js create mode 100644 docs/static/script/anchor-use.js diff --git a/docs/manual.nix b/docs/manual.nix index f5b23d04..b9f9888b 100644 --- a/docs/manual.nix +++ b/docs/manual.nix @@ -8,56 +8,78 @@ # nrd configuration release, optionsJSON, -}: -stdenvNoCC.mkDerivation { - name = "nvf-manual"; - src = builtins.path { - path = lib.sourceFilesBySuffices ./manual [".md"]; +} @ args: let + manual-release = args.release or "unstable"; +in + stdenvNoCC.mkDerivation { name = "nvf-manual"; - }; + src = builtins.path { + name = "nvf-manual-${manual-release}"; + path = lib.sourceFilesBySuffices ./manual [".md" ".md.in"]; + }; - nativeBuildInputs = [nixos-render-docs]; + nativeBuildInputs = [nixos-render-docs]; - buildPhase = '' - dest="$out/share/doc/nvf" - mkdir -p "$(dirname "$dest")" - mkdir -p $dest/{highlightjs,media} + postPatch = '' + ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json + ''; - cp -vt $dest/highlightjs \ - ${documentation-highlighter}/highlight.pack.js \ - ${documentation-highlighter}/LICENSE \ - ${documentation-highlighter}/mono-blue.css \ - ${documentation-highlighter}/loader.js + buildPhase = '' + dest="$out/share/doc/nvf" + mkdir -p "$(dirname "$dest")" + mkdir -p $dest/{highlightjs,script} - substituteInPlace ./options.md \ - --subst-var-by \ - OPTIONS_JSON \ - ${optionsJSON}/share/doc/nixos/options.json + # Copy highlight scripts to /highlights in document root. + cp -vt $dest/highlightjs \ + ${documentation-highlighter}/highlight.pack.js \ + ${documentation-highlighter}/LICENSE \ + ${documentation-highlighter}/mono-blue.css \ + ${documentation-highlighter}/loader.js - substituteInPlace ./manual.md \ - --subst-var-by \ - NVF_VERSION \ - ${release} + cp -vt $dest/script \ + ${./static/script}/anchor-min.js \ + ${./static/script}/anchor-use.js - # copy stylesheet - cp ${./static/style.css} "$dest/style.css" + substituteInPlace ./options.md \ + --subst-var-by OPTIONS_JSON ./config-options.json - # copy release notes - cp -vr ${./release-notes} release-notes + substituteInPlace ./manual.md \ + --subst-var-by NVF_VERSION ${manual-release} \ + --subst-var-by NVF_SRC "https://github.com/nvf/blob/${manual-release}" - # generate manual from - nixos-render-docs manual html \ - --manpage-urls ${path + "/doc/manpage-urls.json"} \ - --revision ${lib.trivial.revisionWithDefault release} \ - --stylesheet style.css \ - --script highlightjs/highlight.pack.js \ - --script highlightjs/loader.js \ - --toc-depth 2 \ - --section-toc-depth 1 \ - manual.md \ - "$dest/index.xhtml" + # copy stylesheet + cp ${./static/style.css} "$dest/style.css" - mkdir -p $out/nix-support/ - echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products - ''; -} + + # copy release notes + cp -vr ${./release-notes} release-notes + + # Generate final manual from a set of parameters. Explanation of the CLI flags are + # as follows: + # + # 1. --manpage-urls will allow you to use manual pages as they are defined in + # the nixpkgs documentation. + # 2. --revision is the project revision as it is defined in 'release.json' in the + # repository root + # 3. --script will inject a given Javascript file into the resulting pages inside + # the