doc: add TLDR and hide details (#195)

* doc: add TLDR * chore(doc): auto generate docs * doc: remove heading for better helpdoc generation * chore(doc): auto generate docs * doc: add help tag links * chore(doc): auto generate docs --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
nvimdev · Feb 22, 2025 · f574be2 · f574be2
1 parent 6c7f7b5
commit f574be2
Show file tree

Hide file tree

Showing 2 changed files with 182 additions and 129 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,3 @@
-# guard.nvim
-
 [![LuaRocks](https://img.shields.io/luarocks/v/xiaoshihou514/guard.nvim?logo=lua&color=green)](https://luarocks.org/modules/xiaoshihou514/guard.nvim)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nvimdev/guard.nvim/test.yml?label=tests)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nvimdev/guard.nvim/ci.yml?label=lint)
@@ -13,94 +11,116 @@ Async formatting and linting utility for neovim `0.10+`.
 - Minimal API allowing for full customization
 - Light-weight
 
-## Usage
+## TLDR
 
-For rocks.nvim
+[`help guard.nvim-tldr`](#tldr)
 
-```vim
-Rocks install guard.nvim
+- Install with your favorite package manager
+
+```
+nvimdev/guard.nvim
 ```
 
-For lazy.nvim
+- Register formatters:
 
 ```lua
-{
-    "nvimdev/guard.nvim",
-    -- lazy load by ft
-    ft = { "lua", "c", "markdown" },
-    -- Builtin configuration, optional
-    dependencies = {
-        "nvimdev/guard-collection",
-    },
-}
+local ft = require('guard.filetype')
+ft('c'):fmt('clang-format')
 ```
 
-To register formatters and linters:
+[demo](https://github.com/user-attachments/assets/3160f979-6683-4288-870d-2447ee445431)
+
+- Register linters
 
 ```lua
 local ft = require('guard.filetype')
+ft('lua'):lint('selene')
+```
 
--- Assuming you have guard-collection
--- Put this in your ftplugin/lang.lua to lazy load guard
-ft('lang'):fmt('format-tool-1')
-          :append('format-tool-2')
-          :env(env_table)
-          :lint('lint-tool-1')
-          :extra(extra_args)
+[demo](https://github.com/user-attachments/assets/2ee2fdaa-42b2-41b3-80ad-26a53bf16809)
 
--- change this anywhere in your config (or not), these are the defaults
-vim.g.guard_config = {
-    -- format on write to buffer
-    fmt_on_save = true,
-    -- use lsp if no formatter was defined for this filetype
-    lsp_as_default_formatter = false,
-    -- whether or not to save the buffer after formatting
-    save_on_fmt = true,
-    -- automatic linting
-    auto_lint = true,
-    -- how frequently can linters be called
-    lint_interval = 500
-}
+- They can also be chained together:
+
+```lua
+local ft = require('guard.filetype')
+ft('haskell'):fmt('ormolu')
+             :lint('hlint')
 ```
 
-- Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting is best-effort, expect inconsistencies.
-- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer.
-- Use `Guard Lint` to lint manually.
-- `enable-lint` and `disable-lint` controls auto linting for the current buffer.
+- Formatters and linters can also be chained:
 
-## Examples
+```lua
+local ft = require('guard.filetype')
+ft('python'):fmt('isort')
+            :append('black')
+            :lint('mypy')
+            :append('mypyc')
+            :append('dmypy')
+```
 
-Format c files with clang-format and lint with clang-tidy:
+- You can register the same formatter for multiple filetypes:
 
 ```lua
-ft('c'):fmt('clang-format')
-       :lint('clang-tidy')
+local ft = require('guard.filetype')
+ft('typescript,javascript,typescriptreact'):fmt('prettier')
 ```
 
-Or use lsp to format lua files first, then format with stylua, then lint with selene:
+- Lint all your files with `codespell`
 
 ```lua
-ft('lua'):fmt('lsp')
-        :append('stylua')
-        :lint('selene')
+-- this does not work with formatters
+ft('*'):lint('codespell')
 ```
 
-Register multiple filetypes to a single linter or formatter:
+- Custom formatters:
 
 ```lua
-ft('typescript,javascript,typescriptreact'):fmt('prettier')
+-- always use 4 spaces for c files
+ft('c'):fmt({
+    cmd = "clang-format",
+    args = { "--style={IndentWidth: 4}" },
+    stdin = true,
+})
 ```
 
-Lint all your files with `codespell`
+## Usage
+
+[`help guard.nvim-usage`](#usage)
+
+Some presets can be configured via `vim.g.guard_config`
 
 ```lua
--- NB: this does not work with formatters
-ft('*'):lint('codespell')
+-- defaults
+vim.g.guard_config = {
+    -- format on write to buffer
+    fmt_on_save = true,
+    -- use lsp if no formatter was defined for this filetype
+    lsp_as_default_formatter = false,
+    -- whether or not to save the buffer after formatting
+    save_on_fmt = true,
+    -- automatic linting
+    auto_lint = true,
+    -- how frequently can linters be called
+    lint_interval = 500
+}
 ```
 
-You can also easily create your own configuration that's not in `guard-collection`, see [CUSTOMIZE.md](./CUSTOMIZE.md).
+Here are all the `Guard` subcommands
+
+|        Name        |                                       Desc                                       |
+| :----------------: | :------------------------------------------------------------------------------: |
+|     Guard fmt      | Manually call format, also works with visual mode (best effort range formatting) |
+|     Guard lint     |                            Manually request for lint                             |
+|  Guard enable-fmt  |                 Turns auto formatting on for the current buffer                  |
+| Guard disable-fmt  |                 Turns auto formatting off for the current buffer                 |
+| Guard enable-lint  |                     Turns linting on for the current buffer                      |
+| Guard disable-lint |                     Turns linting off for the current buffer                     |
+
+## Further configuration
+
+You can easily create your own configuration that's not in `guard-collection`, see [`help guard.nvim-creating-new-configurations`](./CUSTOMIZE.md).
 
-For more niche use cases, [ADVANCED.md](./ADVANCED.md) demonstrates how to:
+For more niche use cases, [`help guard.nvim-advanced-tips`](./ADVANCED.md) demonstrates how to:
 
 - Write your own formatting logic using the `fn` field.
 - Write your own linting logic using the `fn` field.