docs/hacking: add contributing guidelines

docs/default.nix

@@ -3,24 +3,41 @@
   lib ? import ../lib/stdlib-extended.nix pkgs.lib,
   nmdSrc,
 }: let
-  nmd = import nmdSrc {inherit lib pkgs;};
+  nmd = import nmdSrc {
+    inherit lib;
+    # The DocBook output of `nixos-render-docs` doesn't have the change
+    # `nmd` uses to work around the broken stylesheets in
+    # `docbook-xsl-ns`, so we restore the patched version here.
+    pkgs =
+      pkgs
+      // {
+        docbook-xsl-ns =
+          pkgs.docbook-xsl-ns.override {withManOptDedupPatch = true;};
+      };
+  };
+
+  # Make sure the used package is scrubbed to avoid actually
+  # instantiating derivations.
   scrubbedPkgsModule = {
     imports = [
       {
         _module.args = {
           pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs);
+          pkgs_i686 = lib.mkForce {};
         };
       }
     ];
   };
 
+  dontCheckDefinitions = {_module.check = false;};
+
   nvimModuleDocs = nmd.buildModulesDocs {
     modules =
       import ../modules/modules.nix {
         inherit pkgs lib;
         check = false;
       }
-      ++ [scrubbedPkgsModule];
+      ++ [scrubbedPkgsModule dontCheckDefinitions];
     moduleRootPaths = [./..];
     mkModuleUrl = path: "https://github.com/notashelf/neovim-flake/blob/main/${path}#blob-path";
     channelName = "neovim-flake";

docs/man-configuration.xml

@@ -14,7 +14,8 @@
  <refsection>
   <title>Description</title>
   <para>
-    Custom configuration is done with the neovim-flake.lib.neovimConfiguration function. It takes in the configuration as a module.
+      Custom configuration is done with the neovim-flake.lib.neovimConfiguration if home-manager module is not in use.
+      It takes in the configuration as a module.
     <programlisting>
       neovim-flake.lib.neovimConfiguration {
         inherit pkgs;
@@ -31,6 +32,8 @@
       neovim = "The built neovim package";
     }
   </programlisting>
+    In case of the home-manager module, all options will be available under programs.neovim-flake once the module has
+    been imported from the flake inputs.
  </refsection>
  <refsection>
   <title>Options</title>

docs/manual.xml

@@ -9,11 +9,10 @@
  <preface>
   <title>Preface</title>
   <para>
-   If your problem is caused by a bug in neovim-flake then it should be reported on the
+   If you believe your problem is caused by a bug in neovim-flake then please consider reporting it over
-   <link xlink:href="https://github.com/notashelf/neovim-flake/issues">neovim-flake issue tracker</link>.
+   <link xlink:href="https://github.com/notashelf/neovim-flake/issues">the neovim-flake issue tracker</link>.
-   Alongside bug reports, feature requests are also welcome over 
+   Bugfixes, feature additions and upstream changes are welcome over
-   <link xlink:href="https://github.com/notashelf/neovim-flake/pulls">neovim-flake pull requests</link>.
+   <link xlink:href="https://github.com/notashelf/neovim-flake/pulls">the neovim-flake pull requests tab</link>.
-
   </para>
  </preface>
  <xi:include href="manual/try-it-out.xml"/>
@@ -23,6 +22,7 @@
  <xi:include href="manual/custom-package.xml"/>
  <xi:include href="manual/home-manager.xml"/>
  <xi:include href="manual/languages.xml"/>
+ <xi:include href="manual/hacking.xml"/>
  <appendix xml:id="ch-options">
   <title>Configuration Options</title>
   <xi:include href="./nmd-result/neovim-flake-options.xml" />

docs/manual/hacking.adoc

@@ -0,0 +1,370 @@
+[[ch-hacking]]
+== Hacking neovim-flake
+
+<<<<<<< HEAD
+neovim-flake 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
+||||||| parent of c609a56 (among us)
+neovim-flake 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
+=======
+neovim-flake 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
+>>>>>>> c609a56 (among us)
+into neovim-flake's development without leaving question marks in your head.
+
+:open-issues: https://github.com/notashelf/neovim-flake/issues
+:new-issue: https://github.com/notashelf/neovim-flake/issues/new
+:seven-rules: https://cbea.ms/git-commit/#seven-rules
+:example-commit-message: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
+
+This section is mainly directed towards those who wish to contribute code into neovim-flake. If you wish to instead
+report a bug or discuss a potential feature implementation, first look among the already {open-issues}[open issues] and
+if no matching issue exists you may open a {new-issue}[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.
+
+[[sec-contrib-getting-started]]
+==== Getting started
+
+You naturally would like to start by forking the repository. If you are new to git, have a look at GitHub's
+{fork-a-repo}[Fork a repo guide] for instructions on how you can do this. Once you have a fork of neovim-flake
+you should create a branch starting at the most recent `main` branch.
+Give your branch a reasonably descriptive name, suffixed by its type - i.e `feature/debugger` or `fix/pesky-bug`.
+
+Implement your changes and commit them to the newly created branch and when you are happy with the result and positive that it
+fulfills <<sec-guidelines>>. Once you are confident everything is in order, push the branch to GitHub and
+{create-a-pull-request}[create a pull request], following the template that you will be prompted to fill.
+
+[[sec-guidelines]]
+=== Guidelines
+:assertions: https://nixos.org/manual/nixos/stable/index.html#sec-assertions
+:discussions-tab: https://github.com/NotAShelf/neovim-flake/discussions
+
+If your contribution tightly follows the guidelines, then there is a good chance it will be merged without too much
+trouble. Some of the guidelines will be strictly enforced, others will remain as gentle nudges towards the correct
+direction. As we have no automated system enforcing those guidelines, please try to double check your changes before
+making your pull request in order to avoid "faulty" code slipping by.
+
+If you are uncertain how these rules affect the change you would like to make then feel free to start a
+discussion in the {discussions-tab}[discussions tab] ideally (but not necessarily) before you start developing.
+
+[[sec-documentation]]
+==== Add adequate documentation
+:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
+:docbook: https://tdg.docbook.org/
+:asciidoc: https://asciidoc.org/
+
+Most, if not all, changes warrant changes to the documentation. Module options should be documented with
+{nixpkgs-markdown}[Nixpkgs-flavoured Markdown], albeit with exceptions.
+neovim-flake is itself documented using a combination of {docbook}[DocBook] and {asciidoc}[AsciiDoc] conventions.
+
+The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake
+(such as this page) can be generated and opened by typing the following in a shell within a clone of the
+neovim-flake Git repository:
+
+[source,console]
+----
+$ nix build .#docs-html
+$ xdg-open ./result/share/doc/neovim-flake/index.html
+----
+
+[[sec-guidelines-code-style]]
+==== Format your code
+
+Make sure your code is formatted as described in <<sec-code-style>>. To maintain consistency throughout the project
+you are encouraged to browse through existing code and adopt its style also in new code.
+
+[[sec-guidelines-commit-message-style]]
+==== Format your commit messages
+
+Similar to <<sec-guidelines-code-style>> we encourage a consistent commit message format as described
+in <<sec-commit-style>>.
+
+[[sec-commit-style]]
+==== Commits
+
+The commits in your pull request should be reasonably self-contained. Which means each and every commit in
+a pull request should make sense both on its own and in general context. That is, a second commit should not resolve
+an issue that is introduced in an earlier commit.  In particular, you will be asked to amend any commit that
+introduces syntax errors or similar problems even if they are fixed in a later commit.
+
+The commit messages should follow the {seven-rules}[seven rules], except for "Capitalize the subject line".
+We also ask you to include the affected code component or module in the first line.
+A commit message ideally, but not necessarily, follow the given template from home-manager's own documentation
+
+----
+{component}: {description}
+
+{long description}
+----
+
+where `{component}` refers to the code component (or module) your change affects, `{description}` is a very brief
+description of your change, and `{long description}` is an optional clarifying description. As a rare exception, if
+there is no clear component, or your change affects many components, then the `{component}` part is optional.
+See <<ex-commit-message>> for a commit message that fulfills these requirements.
+
+[[ex-commit-message]]
+.Compliant commit message
+===============================================================================
+The commit {example-commit-message}[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef] contains the commit message
+
+----
+starship: allow running in Emacs if vterm is used
+
+The vterm buffer is backed by libvterm and can handle Starship prompts
+without issues.
+----
+===============================================================================
+
+Long description can be ommitted if the change is too simple to warrant it. A minor fix in spelling or a formatting
+change does not warrant long description, however, a module addition or removal does as you would like to provide the
+relevant context for your changes.
+
+Finally, when adding a new module, say `modules/foo.nix`, we use the fixed commit format `foo: add module`.
+You can, of course, still include a long description if you wish.
+
+In case of nested modules, i.e `modules/languages/java.nix` you are recommended to contain the parent as well - for
+example `languages/java: some major change`.
+
+
+[[sec-code-style]]
+==== Code Style
+:alejandra: https://github.com/kamadorueda/alejandra
+
+**Treewide**
+Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals and module
+descriptions and documentation.
+
+**Nix**
+neovim-flake is formatted by the {alejandra}[alejandra] tool and the formatting is checked in the pull
+request and push workflows. Run the `nix fmt` command inside the project repository before submitting your
+pull request.
+
+While Alejandra is mostly opinionated on how code looks after formatting, certain changes are done at the
+user's discretion based on how the original code was structured.
+
+Please use one line code for attribute sets that contain only one subset.
+For example:
+
+[source,nix]
+----
+# parent modules should always be unfolded
+module = {
+    value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
+
+    # same as parent modules, unfold submodules
+    subModule = {
+        # this is an option that contains more than one nested value
+        someOtherValue = mkOption {
+            type = lib.types.bool;
+            description = "Some other description"
+            default = true;
+        };
+    };
+}
+----
+
+If you move a line down after the merge operator, Alejandra will automatically unfold the whole merged attrset
+for you, which we **do not** want.
+
+[source,nix]
+----
+module = {
+    key = mkEnableOption "some description" // {
+        default = true; # we want this to be inline
+    };
+    # ...
+}
+----
+
+For lists, it is mostly up to your own discretion how you want to format them, but please try to unfold lists if
+they contain multiple items and especially if they are to include comments.
+
+[source,nix]
+----
+# this is ok
+acceptableList = [
+    item1 # comment
+    item2
+    item3 # some other comment
+    item4
+];
+
+# this is not ok
+listToBeAvoided = [item1 item2 /* comment */ item3 item4];
+
+# this is ok
+singleItemList = [item1];
+----
+
+[[sec-keybinds]]
+=== Keybinds
+As of 0.4, there exists an API for writing your own keybinds and a couple of useful utility functions are available in
+the https://github.com/NotAShelf/neovim-flake/tree/main/lib[extended standard library]. The following section contains
+a general overview to how you may utilize said functions.
+
+[[sec-custom-key-mappings]]
+=== Custom Key Mappings Support for a Plugin
+
+:maps: https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command._name_.action
+
+To set a mapping, you should define it in `vim.maps.<<mode>>`.
+The available modes are:
+
+* normal
+* insert
+* select
+* visual
+* terminal
+* normalVisualOp
+* visualOnly
+* operator
+* insertCommand
+* lang
+* command
+
+An example, simple keybinding, can look like this:
+
+[source,nix]
+----
+{
+  vim.maps.normal = {
+    "<leader>wq" = {
+      action = ":wq<CR>";
+      silent = true;
+      desc = "Save file and quit";
+    };
+  };
+}
+----
+
+There are many settings available in the options. Please refer to the {maps}[documentation] to see a list of them.
+
+`neovim-flake` provides a list of helper commands, so that you don't have to write the mapping attribute sets every
+time:
+
+* `mkBinding = key: action: desc:` - makes a basic binding, with `silent` set to true.
+* `mkExprBinding = key: action: desc:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
+* `mkLuaBinding = key: action: desc:` - makes an expression binding, with `lua`, and `silent` set to true.
+
+Note that the Lua in these bindings is actual Lua, not pasted into a `:lua` command.
+Therefore, you either pass in a function like `require('someplugin').some_function`, without actually calling it,
+or you define your own function, like `function() require('someplugin').some_function() end`.
+
+Additionally, to not have to repeat the descriptions, there's another utility function with its own set of functions:
+
+[source,nix]
+----
+# Utility function that takes two attrsets:
+# { someKey = "some_value" } and
+# { someKey = { description = "Some Description"; }; }
+# and merges them into
+# { someKey = { value = "some_value"; description = "Some Description"; }; }
+
+addDescriptionsToMappings = actualMappings: mappingDefinitions:
+----
+
+This function can be used in combination with the same `mkBinding` functions as above, except they only take two
+arguments - `binding` and `action`, and have different names:
+
+* `mkSetBinding = binding: action:` - makes a basic binding, with `silent` set to true.
+* `mkSetExprBinding = binding: action:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
+* `mkSetLuaBinding = binding: action:` - makes an expression binding, with `lua`, and `silent` set to true.
+
+You can read the source code of some modules to see them in action, but their usage should look something like this:
+
+[source,nix]
+----
+# plugindefinition.nix
+{lib, ...}:
+with lib; {
+  options.vim.plugin = {
+    enable = mkEnableOption "Enable plugin";
+
+    # Mappings should always be inside an attrset called mappings
+    mappings = {
+      # mkMappingOption is a helper function from lib,
+      # that takes a description (which will also appear in which-key),
+      # and a default mapping (which can be null)
+      toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc";
+      toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc";
+
+      toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc";
+      toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb";
+
+      toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc";
+      toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb";
+    };
+  };
+}
+----
+
+[source,nix]
+----
+# config.nix
+{
+  pkgs,
+  config,
+  lib,
+  ...
+}:
+with lib;
+with builtins; let
+  cfg = config.vim.plugin;
+  self = import ./plugindefinition.nix {inherit lib;};
+  mappingDefinitions = self.options.vim.plugin;
+
+  # addDescriptionsToMappings is a helper function from lib,
+  # that merges mapping values and their descriptions
+  # into one nice attribute set
+  mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
+in {
+  config = mkIf (cfg.enable) {
+    # ...
+
+    vim.maps.normal = mkMerge [
+      # mkSetBinding is another helper function from lib,
+      # that actually adds the mapping with a description.
+      (mkSetBinding mappings.findFiles "<cmd> Telescope find_files<CR>")
+      (mkSetBinding mappings.liveGrep "<cmd> Telescope live_grep<CR>")
+      (mkSetBinding mappings.buffers "<cmd> Telescope buffers<CR>")
+      (mkSetBinding mappings.helpTags "<cmd> Telescope help_tags<CR>")
+      (mkSetBinding mappings.open "<cmd> Telescope<CR>")
+
+      (mkSetBinding mappings.gitCommits "<cmd> Telescope git_commits<CR>")
+      (mkSetBinding mappings.gitBufferCommits "<cmd> Telescope git_bcommits<CR>")
+      (mkSetBinding mappings.gitBranches "<cmd> Telescope git_branches<CR>")
+      (mkSetBinding mappings.gitStatus "<cmd> Telescope git_status<CR>")
+      (mkSetBinding mappings.gitStash "<cmd> Telescope git_stash<CR>")
+
+      (mkIf config.vim.lsp.enable (mkMerge [
+        (mkSetBinding mappings.lspDocumentSymbols "<cmd> Telescope lsp_document_symbols<CR>")
+        (mkSetBinding mappings.lspWorkspaceSymbols "<cmd> Telescope lsp_workspace_symbols<CR>")
+
+        (mkSetBinding mappings.lspReferences "<cmd> Telescope lsp_references<CR>")
+        (mkSetBinding mappings.lspImplementations "<cmd> Telescope lsp_implementations<CR>")
+        (mkSetBinding mappings.lspDefinitions "<cmd> Telescope lsp_definitions<CR>")
+        (mkSetBinding mappings.lspTypeDefinitions "<cmd> Telescope lsp_type_definitions<CR>")
+        (mkSetBinding mappings.diagnostics "<cmd> Telescope diagnostics<CR>")
+      ]))
+
+      (
+        mkIf config.vim.treesitter.enable
+        (mkSetBinding mappings.treesitter "<cmd> Telescope treesitter<CR>")
+      )
+    ];
+
+    # ...
+  };
+}
+----
+
+[NOTE]
+====
+If you have come across a plugin that has an API that doesn't seem to easily allow custom keybindings,
+don't be scared to implement a draft PR. We'll help you get it done.
+====