docs: closes #60, consolidate and complete documentation in the help file

Author: cseickel

CONTRIBUTING.md

@@ -32,7 +32,7 @@ optional scope for this project would usually be the source, i.e.
 
 ## Branching
 
-The default branch is et to the current major version to make it simple for end
+The default branch is set to the current major version to make it simple for end
 users visiting the repo. Pull Requests, however, should go to the `main`
 branch. After a short testing period, it will be merged to the current release
 branch.
@@ -41,3 +41,18 @@ This project requires a **linear history**. I don't trust merge commits.
 This means you will have to rebase your branch on main before the pull request
 can be merged. This can get a bit annoying in a busy repository, but I think it
 is worth the effort.
+
+## Documentation
+
+All new features should be documented in the commit they were added in. The
+current strategy is to maintain:
+
+- Config Options: added to [defaults](lua/neo-tree/defaults.lua) and described
+  in comments
+- The README contains "back of the box" high level overview of features. It is
+  meant for people trying to decide if they want to install this plugin or not.
+  It should include refrences to the help file for more information: 
+  `:h neo-tree-setup`
+- The vim help file [doc/neo-tree.txt](doc/neo-tree.txt) is the definitive
+  reference and should contain all information needed to configure and use the
+  plugin.

README.md

@@ -43,103 +43,31 @@ use {
     requires = { 
       "nvim-lua/plenary.nvim",
       "kyazdani42/nvim-web-devicons", -- not strictly required, but recommended
-        "MunifTanjim/nui.nvim" 
+      "MunifTanjim/nui.nvim" 
     },
     config = function ()
-      require("neo-tree").setup({
-        popup_border_style = "rounded",
-        enable_git_status = true,
-        enable_diagnostics = true,
-        filesystem = {
-          filters = { --These filters are applied to both browsing and searching
-            show_hidden = false,
-            respect_gitignore = true,
-          },
-          follow_current_file = false, -- This will find and focus the file in the
-          -- active buffer every time the current file is changed while the tree is open.
-          use_libuv_file_watcher = false, -- This will use the OS level file watchers
-          -- to detect changes instead of relying on nvim autocmd events.
-          window = {
-            position = "left",
-            width = 40,
-            mappings = {
-              ["<2-LeftMouse>"] = "open",
-              ["<cr>"] = "open",
-              ["S"] = "open_split",
-              ["s"] = "open_vsplit",
-              ["C"] = "close_node",
-              ["<bs>"] = "navigate_up",
-              ["."] = "set_root",
-              ["H"] = "toggle_hidden",
-              ["I"] = "toggle_gitignore",
-              ["R"] = "refresh",
-              ["/"] = "filter_as_you_type",
-              --["/"] = "none" -- Assigning a key to "none" will remove the default mapping
-              ["f"] = "filter_on_submit",
-              ["<c-x>"] = "clear_filter",
-              ["a"] = "add",
-              ["d"] = "delete",
-              ["r"] = "rename",
-              ["c"] = "copy_to_clipboard",
-              ["x"] = "cut_to_clipboard",
-              ["p"] = "paste_from_clipboard",
-              ["bd"] = "buffer_delete",
-            }
-          }
-        },
-        buffers = {
-          show_unloaded = true,
-          window = {
-            position = "left",
-            mappings = {
-              ["<2-LeftMouse>"] = "open",
-              ["<cr>"] = "open",
-              ["S"] = "open_split",
-              ["s"] = "open_vsplit",
-              ["<bs>"] = "navigate_up",
-              ["."] = "set_root",
-              ["R"] = "refresh",
-              ["a"] = "add",
-              ["d"] = "delete",
-              ["r"] = "rename",
-              ["c"] = "copy_to_clipboard",
-              ["x"] = "cut_to_clipboard",
-              ["p"] = "paste_from_clipboard",
-            }
-          },
-        },
-        git_status = {
-          window = {
-            position = "float",
-            mappings = {
-              ["<2-LeftMouse>"] = "open",
-              ["<cr>"] = "open",
-              ["S"] = "open_split",
-              ["s"] = "open_vsplit",
-              ["C"] = "close_node",
-              ["R"] = "refresh",
-              ["d"] = "delete",
-              ["r"] = "rename",
-              ["c"] = "copy_to_clipboard",
-              ["x"] = "cut_to_clipboard",
-              ["p"] = "paste_from_clipboard",
-              ["A"]  = "git_add_all",
-              ["gu"] = "git_unstage_file",
-              ["ga"] = "git_add_file",
-              ["gr"] = "git_revert_file",
-              ["gc"] = "git_commit",
-              ["gp"] = "git_push",
-              ["gg"] = "git_commit_and_push",
-            }
-          }
-        }
-      })
+      require("neo-tree").setup() -- This is optional if you are not going to
+                                  -- change any of the defaults.
       vim.cmd([[nnoremap \ :NeoTreeReveal<cr>]])
     end
 }
 ```
-_The above configuration is not everything that can be changed, it's just the
-parts you might want to change first._
+
+See `:h neo-tree` for full documentation. You can also preview that online at
+[doc/neo-tree.txt](doc/neo-tree.txt), although it's best viewed within vim.
+
+
+### Config Options
+
+To see all of the default config options with commentary, you can view it online
+at [lua/neo-tree/defaults.lua](lua/neo-tree/defaults.lua). You can also paste it
+into your config after installing Neo-tree by running `:NeoTreePasteConfig`,
+which will paste the default config as a `config` table into the current buffer.
+You can then change what you want in the pasted `config` table and pass it to
+`require("neo-tree").setup(config)`
+
+
+### Commands
 
 Here are the various ways to open the tree:
 
@@ -181,6 +109,7 @@ at [neo-tree.txt](/doc/neo-tree.txt)
 An example configuration for the filesystem source with proper syntax
 highlighting can also be viewed at the [filesystem README](/lua/neo-tree/sources/filesystem/README.md)
 
+
 ## Sources
 
 Neo-tree is built on the idea of supporting various sources. Sources are
@@ -192,6 +121,13 @@ those items.
 The default source is `filesystem`, which displays your files and folders. This
 is the default source in commands when none is specified.
 
+This source can be used to:
+- Browse the filesystem
+- Control the current working directory of nvim
+- Add/Copy/Delete/Move/Rename files and directories
+- Search the filesystem
+- Monitor git status and lsp diagnostics for the current working directory
+
 ### buffers
 ![Neo-tree buffers](https://github.com/nvim-neo-tree/resources/raw/main/images/Neo-tree-buffers.png)
 
@@ -220,18 +156,24 @@ built-in functions can be replaced with your own implementation, or you can
 add new ones.
 
 Each node in the tree is created from the renderer specified for the given node
-type, and each renderer is a list of component configs to be rendered in order
-for each node in the tree. Each component is a function, either built-in or
-specified in your config. Those functions are called with the config, node, and
-state of the plugin, and return the text and highlight group for the component.
+type, and each renderer is a list of component configs to be rendered in order. 
+Each component is a function, either built-in or specified in your config. Those
+functions simply return the text and highlight group for the component.
 
 Additionally, there is an events system that you can hook into. If you want to
 show some new data point related to your files, gather it in the
 `before_render` event, create a component to display it, and reference that
 component in the renderer for the `file` and/or `directory` type.
 
-Details on how to configure everything is in the help file at `:h neo-tree` or
-online at [neo-tree.txt](https://github.com/nvim-neo-tree/neo-tree.nvim/blob/main/doc/neo-tree.txt)
+Details on how to configure everything is in the help file at `:h
+neo-tree-configuration` or online at
+[neo-tree.txt](https://github.com/nvim-neo-tree/neo-tree.nvim/blob/main/doc/neo-tree.txt)
+
+Recipes for customizations can be found on the [wiki](wiki). Recipes include
+things like adding a component to show the
+[Harpoon](https://github.com/ThePrimeagen/harpoon) index for files, or
+responding to the `"file_opened"` event to auto clear the search when you open a
+file.
 
 
 ## Why?
@@ -276,7 +218,7 @@ major version, and the breaking change will happen in the next major version.
 
 ### Easy to Customize
 
-This will follow in the spirit of plugins like
+Neo-tree follows in the spirit of plugins like
 [lualine.nvim](https://github.com/nvim-lualine/lualine.nvim) and
 [nvim-cokeline](https://github.com/noib3/nvim-cokeline). Everything will be
 configurable and take either strings, tables, or functions. You can take sane