all: improve and update documentation

CODE_OF_CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
+- Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
+- Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
+- Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
+- Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
+- Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

docs/README.md

@@ -4,8 +4,8 @@ Doom Nvim is a port to Neovim of the [Doom Emacs](https://github.com/hlissner/do
 configuration framework for [GNU Emacs](https://www.gnu.org/software/emacs/) adapted
 for all vimmer who want less framework in their framework and the performance of
 a handmade configuration (or better). It can be a base for your own setup or a
-resource for Vim enthusiasts to learn more about our favorite editor and how to
+resource for Neovim enthusiasts to learn more about our favorite editor and how to
-do X things on it by using Vimscript/Lua.
+do X things on it by using Lua.
 
 Doom Nvim is an opinionated collection of reasonable (and optional) defaults with
 a focus on performance (both runtime and startup) and on abstraction-light, readable
@@ -15,6 +15,7 @@ code design, so that there is less between you and Neovim.
 > `:h doom_nvim`.
 
 # Table of Contents
+
 - [Documentation](#documentation)
   - [Getting Started](#getting-started)
   - [Modules](#modules)
@@ -43,7 +44,6 @@ code design, so that there is less between you and Neovim.
 - [Suggesting features, keybinds and enhancements](./contributing.md#suggesting-features-keybinds-and-enhancements)
 - [Contributing code](./contributing.md#contributing-code)
 
-
 # Community Resources
 
 ## Asking for help

docs/contributing.md

@@ -42,17 +42,10 @@ and which code style you should use :heart:
 
 ## Acquire a backtrace from errors
 
-All the errors ocurred in Doom Nvim are saved into a `doom.log` file inside a `logs/`
+All the errors ocurred in Doom Nvim are saved into a `doom.log` file inside the
-directory inside your Doom Nvim root dir (`$HOME/.config/doom-nvim` by default).
+`~/.local/share/nvim/` directory.
 If the logs are very long, please paste it using a [gist].
 
-> **NOTE:** Alternatively you can paste the most recent lines starting with the
-> following if the logs are extremely long.
->
-> [!] - Errors
->
-> [!!!] - Critical errors
-
 ## Create a step-by-step reproduction guide
 
 A step-by-step guide can help considerably to debug the error that occurs and
@@ -84,10 +77,9 @@ type of issue and handle the requests.
 
 Doom Nvim follows some code style rules like ones the mentioned below:
 
-- Single quotes instead of double quotes.
+- Single quotes over double quotes.
 - Variable names in `snake_case`, except in the BASH installation script.
-- Function names in `snake_case`, the only exception are the Vimscript functions
+- Function names in `snake_case`.
-  which does not are from doom itself, e.g. `function ToggleTerm() ... endfunction`.
 - [stylua] is used to format lua files with the following configuration:
 
 ```toml
@@ -99,6 +91,16 @@ quote_style = "AutoPreferSingle"
 
 ```
 
+> **NOTE:** use `--config-path /path/to/doom/nvim/stylua.toml` to use doom's
+> stylua configuration.
+
+- [selene] is a blazing-fast modern Lua linter written in Rust which is used for
+  linting doom's source code. We make use of some custom rules so we can be sure
+  that selene will not raise false errors.
+
+> **NOTE:** use `selene .` in doom's root dir and selene will automatically
+> detect the `selene.toml` and `doom.toml` files.
+
 ### Commits & PRs
 
 - Target `develop` instead of `main`.
@@ -106,8 +108,8 @@ quote_style = "AutoPreferSingle"
 
 ### Keybind conventions
 
-- The keybindings should be declared in [config/keybindings](../lua/doom/keybindings.lua),
+- The keybindings should be declared in [core/keybindings](../lua/doom/core/keybindings/init.lua),
-  except when they are keybindings of [Lua plugins](../lua/plugins/configs).
+  except when they are keybindings of [Lua plugins](../lua/doom/modules/config).
 
 ## Submitting pull requests
 
@@ -116,3 +118,4 @@ they work and do not break any of the current code, you can proceed to upload
 your pull request :)
 
 [stylua]: https://github.com/JohnnyMorganz/StyLua
+[selene]: https://github.com/Kampfkarren/selene

docs/faq.md

@@ -1,6 +1,7 @@
 # Frequently Asked Questions
 
 # Table of Contents
+
 - [General](#general)
   - [What type of vimmer is Doom Nvim intended for?](#what-type-of-vimmer-is-doom-nvim-intended-for)
   - [Why does Doom Nvim only support Neovim nightly?](#why-does-doom-nvim-only-support-neovim-nightly)
@@ -15,6 +16,7 @@ development environment without spending a lot of time setting everything up.
 ## Why does Doom Nvim only support Neovim nightly?
 
 Doom Nvim doesn't support Neovim versions lower than Nightly (0.5) due to:
+
 - some features would be lost
 - Not all Lua plugins have good alternatives in Vimscript, so the experience
   would not be the same

docs/getting_started.md

@@ -17,12 +17,13 @@
     - [On MacOS](#on-macos)
     - [On Windows](#on-windows)
   - [Doom Nvim](#doom-nvim)
+    - [Using cheovim](#using-cheovim)
 - [Update & Rollback](#update--rollback)
   - [Update Doom Nvim](#update-doom-nvim)
   - [Rollback](#rollback)
 - [Configuration](#configuration)
   - [Modules](#modules)
-  - [Package Management](#package-management)
+  - [Plugins Management](#plugins-management)
     - [Installing plugins](#installing-plugins)
     - [Disabling plugins](#disabling-plugins)
   - [Configuring Doom](#configuring-doom)
@@ -58,6 +59,8 @@ of your distribution, so you have several options to install it.
 
 2. Using extra repositories according to your distribution (PPA/COPR/AUR/etc).
 
+3. Using a Neovim version manager like [nvenv](https://github.com/NTBBloodbath/nvenv).
+
 #### Ubuntu
 
 You can get nightly builds of git master from the
@@ -68,6 +71,17 @@ add-apt-repository ppa:neovim-ppa/unstable
 apt-get update
 ```
 
+#### Fedora
+
+Nightly builds can be installed by using the
+[agriffis/neovim-nightly](https://copr.fedorainfracloud.org/coprs/agriffis/neovim-nightly/)
+COPR repository.
+
+```sh
+dnf copr enable agriffis/neovim-nightly
+dnf update
+```
+
 #### Arch
 
 Neovim Nightly builds can be installed using the PKGBUILD
@@ -76,9 +90,18 @@ available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository
 
 ### On MacOS
 
-Neovim nightly can be installed with [homebrew](https://brew.sh/) with the following command.
+You can download a prebuilt binary from the [Neovim](https://github.com/neovim/neovim/releases/tag/nightly) nightly releases page.
+
+1. Download: `curl -LO https://github.com/neovim/neovim/releases/download/nightly/nvim-macos.tar.gz`
+2. Extract: `tar xzvf nvim-macos.tar.gz`
+3. Run: `./nvim-osx64/bin/nvim`
+
+You may wish to add it to your PATH using something like:
+`export PATH="$HOME/nvim-osx64/bin:$PATH"`
 
-`brew install --HEAD neovim`
+Neovim nightly can also be downloaded with [homebrew](https://brew.sh/):
+
+`brew install --HEAD neovim` will download the source and build it locally on your machine.
 
 If you already have Neovim v4 installed you may need to unlink it.
 
@@ -124,8 +147,10 @@ You can also download a prebuilt binary from the [Neovim](https://github.com/neo
 ```sh
 # Required dependencies
 apt-get install git ripgrep
+
 # (Optional) Improves performance for many file indexing commands
 apt-get install fd-find
+
 # (Optional) Required by Language Server Protocols
 apt-get install nodejs npm
 ```
@@ -135,8 +160,10 @@ apt-get install nodejs npm
 ```sh
 # Required dependencies
 dnf install git ripgrep
+
 # (Optional) Improves performance for many file indexing commands
 dnf install fd-find # is 'fd' in Fedora <28
+
 # (Optional) Required by Language Server Protocols
 dnf install nodejs
 ```
@@ -146,8 +173,10 @@ dnf install nodejs
 ```sh
 # Required dependencies
 pacman -S git ripgrep
+
 # (Optional) Improves performance for many file indexing commands
 pacman -S fd
+
 # (Optional) Required by Language Server Protocols
 pacman -S nodejs npm
 ```
@@ -192,6 +221,19 @@ curl -sLf https://raw.githubusercontent.com/NTBBloodbath/doom-nvim/main/install.
 The installation script will set up everything for you and will work you through
 the first-time setup of Doom Nvim.
 
+### Using cheovim
+
+If you're using cheovim as your Neovim configurations manager you can use the
+recipe listed in cheovim documentation:
+
+```lua
+doom_nvim = { "~/.config/doom-nvim", {
+        plugins = "packer",
+        preconfigure = "doom-nvim"
+    }
+}
+```
+
 # Update & Rollback
 
 ## Update Doom Nvim
@@ -209,11 +251,11 @@ and restore the backup of your previous setup.
 
 You can configure Doom Nvim by tweaking the file `doomrc` in your Doom Nvim root
 dir (`$HOME/.config/doom-nvim/` by default), please see
-<kbd>:h doom_nvim</kbd> for more information.
+<kbd>:h doom_nvim_options</kbd> for more information.
 
 > **IMPORTANT:** any changes to your Doom Nvim configuration occassionally
-> need a run of `:PackerSync` inside Neovim. For instance, when you enable
+> need a run of `:PackerSync` inside Neovim (if you're using the stable branch).
-> a disabled plugin.
+> For instance, when you enable a disabled plugin.
 
 ## Modules
 
@@ -221,21 +263,21 @@ Doom Nvim consists of around 7 modules and growing. A Doom Nvim Module is a bund
 configuration and commands, organized into a unit that can be toggled easily by
 tweaking your doomrc (found in `$HOME/.config/doom-nvim`).
 
-Please see [Package Management](#package-management) for more information.
+Please see [Plugins Management](#plugins-management) for more information.
 
 > **IMPORTANT:** any changes to your Doom Nvim Modules won't take effect until
 > you run `:PackerSync` inside Neovim.
 
-## Package Management
+## Plugins Management
 
-Doom Nvim does not use Vim-Plug in the Neovim Nightly version. Instead, it uses
+Doom Nvim uses a declarative and use-package inspired package manager called
-a declarative and use-package inspired package manager called
 [packer.nvim](https://github.com/wbthomason/packer.nvim).
 
-Modules and plugins are declared in `lua/plugins/init.lua` file, located in your Doom Nvim root dir.
+Modules and plugins are declared in `lua/doom/modules/init.lua` file, located
-Read on to learn how to use this system to install your own plugins.
+in your Doom Nvim root dir. Read on to learn how to use this system to install
+your own plugins.
 
-> **WARNING:** Do not install plugins directly in `lua/plugins/init.lua`. Instead,
+> **WARNING:** Do not install plugins directly in `lua/doom/modules/init.lua`. Instead,
 > use your `doomrc` to modify them.
 
 ### Installing plugins
@@ -248,22 +290,25 @@ in your `doomrc`.
 custom_plugins = { 'plugin_author/plugin_repo' }
 ```
 
-You can also use other method if the plugin depends on other plugins.
+You can also use other method if the plugin depends on other plugins. All the
+available options for the plugins can be found on
+[packer.nvim](https://github.com/wbthomason/packer.nvim) README file.
 
 ```lua
 custom_plugins = {
     'plugin_author/plugin_repo',
     {
-        'repo': 'plugin_author/second_plugin_repo',
+        'plugin_author/second_plugin_repo',
-        'enabled': true, -- not required, true by default
+        disable = false, -- not required, false by default
-        'requires': { 'foo', 'bar' } -- not required if the plugin does not have dependencies
+        requires = { 'foo', 'bar' } -- not required if the plugin does not have dependencies
     },
 }
 ```
 
 > **NOTES:**
 >
-> 1. Do not forget to run `:PackerInstall` to install your new plugins.
+> 1. Do not forget to run `:PackerInstall` to install your new plugins if you're
+>    using the stable branch of Doom Nvim.
 
 ### Disabling plugins
 
@@ -275,12 +320,13 @@ To disable plugins from Doom Nvim Modules or disable a module itself, just use t
 disabled_plugins = { 'terminal', 'treesitter' }
 
 -- @default = { 'git', 'lsp', 'web' }
-let g:doom_disabled_modules = { 'web' }
+disabled_modules = { 'web' }
 ```
 
 > **NOTES:**
 >
-> 1. Do not forget to run `:PackerSync` or your changes won't take effect.
+> 1. Do not forget to run `:PackerSync` or your changes won't take effect if you're
+>    using the stable branch of Doom Nvim.
 >
 > 2. You can see a list of the plugins that you can disable on [Modules](./modules.md#list-of-modules).
 >
@@ -291,19 +337,19 @@ let g:doom_disabled_modules = { 'web' }
 ### Configuring settings
 
 You can change Doom's default settings by tweaking your `doomrc`, please see
-<kbd>:h doom_nvim</kbd> to know how to.
+<kbd>:h doom_nvim_options</kbd> to know how to.
 
 ### Configuring plugins
 
 Do you want to change some configurations of some modules?
 
-Go to `lua/plugins/configs` dir and you will find the configurations for the plugins.
+Go to `lua/doom/modules/config` dir and you will find the configurations for the plugins.
 
 #### Configuring LSP
 
 [LSP](https://microsoft.github.io/language-server-protocol/) is installed as a plugin.
 Be aware that this plugin is disabled per default. To enable it, remove it from the
-`Disabled plugins` section in your `doomrc`.
+`disabled_modules` section in your `doomrc`.
 
 To easily install LSPs and without having to do it system-wide or having to
 manually configure servers, Doom Nvim makes use of [kabouzeid/nvim-lspinstall](https://github.com/kabouzeid/nvim-lspinstall).
@@ -319,5 +365,5 @@ You can see a list of currently supported languages at [bundled installers](http
 
 You can modify the default keybindings by modifying the following files:
 
-- `lua/doom/keybindings/init.lua` - General and SPC keybindings
+- `lua/doom/core/keybindings/init.lua` - General and SPC keybindings
-- `lua/plugins/configs` - lua plugins keybindings
+- `lua/doom/modules/config` - lua plugins keybindings

docs/modules.md

@@ -55,7 +55,7 @@ including their plugins individually.
     - Use `tree` to disable it
   - [x] [galaxyline.nvim] - galaxyline is a light-weight and Super Fast statusline plugin.
     - Use `statusline` to disable it
-  - [x] [barbar.nvim] - Tabs, as understood by any other editor.
+  - [x] [nvim-bufferline.lua] - Tabs, as understood by any other editor.
     - Use `tabline` to disable it
   - [x] [nvim-toggleterm.lua] - A neovim plugin to persist and toggle multiple terminals during an editing session
     - Use `terminal` to disable it
@@ -98,6 +98,10 @@ including their plugins individually.
     - **NOTE:** do not disable it if you are going to use LSP!
   - [x] [nvim-compe] - Auto completion plugin for nvim that written in Lua.
     - Use `compe` to disable it
+  - [x] [lspsaga.nvim] - A light-weight lsp plugin based on neovim built-in lsp with highly a performant UI.
+    - Use `lspsaga` to disable it
+  - [x] [nvim-lspinstall] - Provides the missing :LspInstall for nvim-lspconfig.
+    - Use `lspinstall` to disable it
 
 ### Files
 
@@ -109,9 +113,9 @@ including their plugins individually.
     - Use `suda` to disable it
   - [x] [format.nvim] - Neovim lua plugin to format the current buffer with external executables.
     - Use `formatter` to disable it
-  - [x] [pears.nvim] - Auto pair plugin for neovim
+  - [x] [nvim-autopairs] - A super powerful autopairs for Neovim.
     - Use `autopairs` to disable it
-  - [x] [indentLine] - A vim plugin to display the indention levels with thin vertical lines
+  - [x] [indent-blankline.nvim] - Indent guides for Neovim
     - Use `indentlines` to disable it
   - [x] [editorconfig-vim] - EditorConfig support
     - Use `editorconfig` to disable it
@@ -188,7 +192,7 @@ disabled_plugins = { 'emmet' }
 [dashboard-nvim]: https://github.com/glepnir/dashboard-nvim
 [nvim-tree.lua]: https://github.com/kyazdani42/nvim-tree.lua
 [galaxyline.nvim]: https://github.com/glepnir/galaxyline.nvim
-[barbar.nvim]: https://github.com/romgrk/barbar.nvim
+[nvim-bufferline.lua]: https://github.com/akinsho/nvim-bufferline.lua
 [nvim-toggleterm.lua]: https://github.com/akinsho/nvim-toggleterm.lua
 [symbols-outline.nvim]: https://github.com/simrat39/symbols-outline.nvim
 [minimap.vim]: https://github.com/wfxr/minimap.vim
@@ -207,11 +211,16 @@ disabled_plugins = { 'emmet' }
 <!-- LSP -->
 
 [nvim-lspconfig]: https://github.com/neovim/nvim-lspconfig
-[nvim-compe]: <!-- Files -->
+[nvim-compe]: https://github.com/hrsh7th/nvim-compe
+[lspsaga.nvim]: https://github.com/glepnir/lspsaga.nvim
+[nvim-lspinstall]: https://github.com/kabouzeid/nvim-lspinstall
+
+<!-- Files -->
+
 [suda.vim]: https://github.com/lambdalisue/suda.vim
 [format.nvim]: https://github.com/lukas-reineke/format.nvim
-[pears.nvim]: https://github.com/steelsojka/pears.nvim
+[nvim-autopairs]: https://github.com/windwp/nvim-autopairs
-[indentline]: https://github.com/Yggdroot/indentLine
+[indent-blankline.nvim]: https://github.com/lukas-reineke/indent-blankline.nvim
 [editorconfig-vim]: https://github.com/editorconfig/editorconfig-vim
 [kommentary]: https://github.com/b3nj5m1n/kommentary
 

lua/colors/README.md

@@ -0,0 +1,59 @@
+# Colors
+
+This module contains the embedded colorschemes for Doom Nvim and the utils
+module required by those colorschemes.
+
+Actually the embedded colorschemes are the following:
+
+- doom-one (dark and light variant)
+
+## utils
+
+The utils module contains a few utilities for easily port Doom Emacs colorschemes
+to Lua colorschemes. These utilities are the following:
+
+- `Lighten` - lighten the provided HEX color in X percentage (5 by default).
+- `Darken` - darken the provided HEX color in X percentage (5 by default).
+- `Mix` - mix two provided HEX colors in X percentage (0 by default)
+
+## Contributing
+
+### Write colorschemes
+
+If you want to write colorschemes for Doom Nvim you will need to follow some
+requirements.
+
+- The colorscheme should be a Doom Emacs colorscheme, see [emacs-doom-themes].
+- The colorscheme should be written in pure Lua **without using helpers like lush**,
+  you can take a look at [doom-one] source or use it as a template (highly recommended).
+
+### Update embedded colorschemes
+
+If you want to update the embedded colorschemes like [doom-one] you'll need to
+copy the doom-one files to the proper locations and change a few lines to match
+Doom Nvim structure.
+
+- Changes in `colors/doom-one.lua`:
+
+```lua
+--- FROM:
+package.loaded['doom-one'] = nil
+require('doom-one')
+
+--- TO:
+package.loaded['colors.doom-one'] = nil
+require('colors.doom-one')
+```
+
+- Changes in `doom-one/init.lua`:
+
+```lua
+--- FROM:
+local utils = require('utils')
+
+--- TO:
+local utils = require('colors.utils')
+```
+
+[doom-one]: https://github.com/NTBBloodbath/doom-one.nvim
+[emacs-doom-themes]: https://github.com/hlissner/emacs-doom-themes

lua/doom/README.md

@@ -0,0 +1,11 @@
+# Doom
+
+This is the entry point module for Doom Nvim. Herein lies the core of Doom
+divided into three different sub-modules.
+
+- [core](./core/README.md) - The Doom core, herein lies the entire Doom core,
+    e.g. configurations, keybindings.
+- [modules](./modules/README.md) - The Doom modules, herein lies the Doom plugins
+    and their configurations.
+- [utils](./utils/README.md) - The Doom utilities, herein lies the Doom utility
+    functions.

lua/doom/core/README.md

@@ -0,0 +1,15 @@
+# Core
+
+Herein lies the core of Doom. In other words, the modules needed for Doom to
+be Doom.
+
+Those modules are the following:
+
+- autocmds - Doom autocommands.
+- config - Doom configurations, handles doomrc file and UI settings.
+- default - Doom configurations for Neovim, e.g. `tabwidth`, `showmode`.
+- functions - Doom core functions, e.g. `create_report`.
+- health - Doom health add-on.
+- keybindings - Doom keybindings.
+- logging - Doom logging system.
+- system - Doom system detection (unused at the moment).

lua/doom/modules/README.md

@@ -0,0 +1,6 @@
+# Modules
+
+Herein lies all the Doom plugins and their configurations.
+
+Refer to [List of modules](../../../docs/modules.md#list-of-modules) for more
+information about what's inside this module.

lua/doom/utils/README.md

@@ -0,0 +1,19 @@
+# Utils
+
+Herein lies all the Doom utility functions and variables.
+
+## Variables
+
+- `doom_version` - Doom Nvim version.
+- `doom_root` - Doom Nvim root directory.
+- `doom_logs` - Doom Nvim logs file path.
+- `doom_report` - Doom Nvim crash report path.
+
+## Functions
+
+- `map` - Wrapper for `nvim_set_keymap`.
+- `create_augroups` - Autocommands wrapper for Lua.
+- `is_empty` - Check if a string is empty or nil.
+- `has_value` - Search if a table have a value.
+- `try` and `catch` - Try/Catch for error handling.
+- `get_os` - Get the current OS using LuaJIT.