From 2340d669b977f8650881f4c159589495fb441b3e Mon Sep 17 00:00:00 2001 From: NTBBloodbath Date: Tue, 22 Jun 2021 00:39:18 -0400 Subject: [PATCH] all: improve and update documentation --- CODE_OF_CONDUCT.md | 22 ++++----- docs/README.md | 6 +-- docs/contributing.md | 31 ++++++------ docs/faq.md | 2 + docs/getting_started.md | 96 ++++++++++++++++++++++++++++---------- docs/modules.md | 23 ++++++--- lua/colors/README.md | 59 +++++++++++++++++++++++ lua/doom/README.md | 11 +++++ lua/doom/core/README.md | 15 ++++++ lua/doom/modules/README.md | 6 +++ lua/doom/utils/README.md | 19 ++++++++ 11 files changed, 230 insertions(+), 60 deletions(-) create mode 100644 lua/colors/README.md create mode 100644 lua/doom/README.md create mode 100644 lua/doom/core/README.md create mode 100644 lua/doom/modules/README.md create mode 100644 lua/doom/utils/README.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 3f2111b..e825e03 100644 --- a/CODE_OF_CONDUCT.md +++ b/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 -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- 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 -* Public or private harassment -* Publishing others' private information, such as a physical or email +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- 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 diff --git a/docs/README.md b/docs/README.md index 3f39a66..8cc69e2 100644 --- a/docs/README.md +++ b/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 -do X things on it by using Vimscript/Lua. +resource for Neovim enthusiasts to learn more about our favorite editor and how to +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 diff --git a/docs/contributing.md b/docs/contributing.md index 245aee5..4cf24b2 100644 --- a/docs/contributing.md +++ b/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/` -directory inside your Doom Nvim root dir (`$HOME/.config/doom-nvim` by default). +All the errors ocurred in Doom Nvim are saved into a `doom.log` file inside the +`~/.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 - which does not are from doom itself, e.g. `function ToggleTerm() ... endfunction`. +- Function names in `snake_case`. - [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), - except when they are keybindings of [Lua plugins](../lua/plugins/configs). +- The keybindings should be declared in [core/keybindings](../lua/doom/core/keybindings/init.lua), + 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 diff --git a/docs/faq.md b/docs/faq.md index f74b396..9071144 100644 --- a/docs/faq.md +++ b/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 diff --git a/docs/getting_started.md b/docs/getting_started.md index 014ed76..9e63817 100644 --- a/docs/getting_started.md +++ b/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 -:h doom_nvim for more information. +:h doom_nvim_options for more information. > **IMPORTANT:** any changes to your Doom Nvim configuration occassionally -> need a run of `:PackerSync` inside Neovim. For instance, when you enable -> a disabled plugin. +> need a run of `:PackerSync` inside Neovim (if you're using the stable branch). +> 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 -a declarative and use-package inspired package manager called +Doom Nvim uses 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. -Read on to learn how to use this system to install your own plugins. +Modules and plugins are declared in `lua/doom/modules/init.lua` file, located +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', - 'enabled': true, -- not required, true by default - 'requires': { 'foo', 'bar' } -- not required if the plugin does not have dependencies + 'plugin_author/second_plugin_repo', + disable = false, -- not required, false by default + 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 -:h doom_nvim to know how to. +:h doom_nvim_options 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/plugins/configs` - lua plugins keybindings +- `lua/doom/core/keybindings/init.lua` - General and SPC keybindings +- `lua/doom/modules/config` - lua plugins keybindings diff --git a/docs/modules.md b/docs/modules.md index 3afe4f5..2536241 100644 --- a/docs/modules.md +++ b/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' } [nvim-lspconfig]: https://github.com/neovim/nvim-lspconfig -[nvim-compe]: +[nvim-compe]: https://github.com/hrsh7th/nvim-compe +[lspsaga.nvim]: https://github.com/glepnir/lspsaga.nvim +[nvim-lspinstall]: https://github.com/kabouzeid/nvim-lspinstall + + + [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 -[indentline]: https://github.com/Yggdroot/indentLine +[nvim-autopairs]: https://github.com/windwp/nvim-autopairs +[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 diff --git a/lua/colors/README.md b/lua/colors/README.md new file mode 100644 index 0000000..36efdbb --- /dev/null +++ b/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 diff --git a/lua/doom/README.md b/lua/doom/README.md new file mode 100644 index 0000000..f6231b1 --- /dev/null +++ b/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. diff --git a/lua/doom/core/README.md b/lua/doom/core/README.md new file mode 100644 index 0000000..45b4d3b --- /dev/null +++ b/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). diff --git a/lua/doom/modules/README.md b/lua/doom/modules/README.md new file mode 100644 index 0000000..f4040bf --- /dev/null +++ b/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. diff --git a/lua/doom/utils/README.md b/lua/doom/utils/README.md new file mode 100644 index 0000000..9525138 --- /dev/null +++ b/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.