chore: set up cbfmt and format documentation (#981)

Author: Jose Alvarez

.cbfmt.toml

@@ -0,0 +1,2 @@
+[languages]
+lua = ["stylua -s -"]

README.md

@@ -154,9 +154,9 @@ local markdownlint = {
             local success = code <= 1
 
             if not success then
-              -- can be noisy for things that run often (e.g. diagnostics), but can
-              -- be useful for things that run on demand (e.g. formatting)
-              print(stderr)
+                -- can be noisy for things that run often (e.g. diagnostics), but can
+                -- be useful for things that run on demand (e.g. formatting)
+                print(stderr)
             end
 
             return success
@@ -231,7 +231,7 @@ use a plugin like [trouble.nvim](https://github.com/folke/trouble.nvim).
 
    ```lua
    require("null-ls").setup({
-       debug = true
+       debug = true,
    })
    ```
 

doc/BUILTINS.md

@@ -708,12 +708,11 @@ Shader to SPIR-V compiler.
 #### Usage
 
 ```lua
-        local sources = {
-            null_ls.builtins.diagnostics.glslc.with({
-                extra_args = { "--target-env=opengl" } -- use opengl instead of vulkan1.0
-            })
-        }
-        
+local sources = {
+    null_ls.builtins.diagnostics.glslc.with({
+        extra_args = { "--target-env=opengl" }, -- use opengl instead of vulkan1.0
+    }),
+}
 ```
 
 #### Defaults
@@ -1344,9 +1343,9 @@ A SQL linter and auto-formatter for Humans
 
 ```lua
 local sources = {
-	null_ls.builtins.diagnostics.sqlfluff.with({
-		extra_args = {"--dialect", "postgres"} -- change to your dialect
-	})
+    null_ls.builtins.diagnostics.sqlfluff.with({
+        extra_args = { "--dialect", "postgres" }, -- change to your dialect
+    }),
 }
 ```
 
@@ -3175,9 +3174,9 @@ A SQL linter and auto-formatter for Humans
 
 ```lua
 local sources = {
-	null_ls.builtins.formatting.sqlfluff.with({
-		extra_args = {"--dialect", "postgres"} -- change to your dialect
-	})
+    null_ls.builtins.formatting.sqlfluff.with({
+        extra_args = { "--dialect", "postgres" }, -- change to your dialect
+    }),
 }
 ```
 

doc/BUILTIN_CONFIG.md

@@ -19,20 +19,22 @@ null-ls exposes built-ins on `null_ls.builtins`, which contains the following
 groups of sources:
 
 ```lua
+local null_ls = require("null-ls")
+
 -- code action sources
-null_ls.builtins.code_actions
+local code_actions = null_ls.builtins.code_actions
 
 -- diagnostic sources
-null_ls.builtins.diagnostics
+local diagnostics = null_ls.builtins.diagnostics
 
 -- formatting sources
-null_ls.builtins.formatting
+local formatting = null_ls.builtins.formatting
 
 -- hover sources
-null_ls.builtins.hover
+local hover = null_ls.builtins.hover
 
 -- completion sources
-null_ls.builtins.completion
+local completion = null_ls.builtins.completion
 ```
 
 You can then register sources by passing a `sources` list into your `setup`
@@ -115,9 +117,9 @@ To add more arguments to a source's defaults, use `extra_args`:
 ```lua
 local sources = {
     null_ls.builtins.formatting.shfmt.with({
-        extra_args = { "-i", "2", "-ci" }
-      })
-  }
+        extra_args = { "-i", "2", "-ci" },
+    }),
+}
 ```
 
 You can also override a source's arguments entirely using `with({ args = your_args })`.
@@ -151,9 +153,9 @@ operating system variables.
 ```lua
 local sources = {
     null_ls.builtins.formatting.prettierd.with({
-          env = {
-            PRETTIERD_DEFAULT_CONFIG = vim.fn.expand "~/.config/nvim/utils/linter-config/.prettierrc.json",
-          }
+        env = {
+            PRETTIERD_DEFAULT_CONFIG = vim.fn.expand("~/.config/nvim/utils/linter-config/.prettierrc.json"),
+        },
     }),
 }
 ```
@@ -181,8 +183,8 @@ local sources = {
     null_ls.builtins.diagnostics.eslint_d.with({
         -- ignore prettier warnings from eslint-plugin-prettier
         filter = function(diagnostic)
-            return diagnostic.code != "prettier/prettier"
-        end
+            return diagnostic.code ~= "prettier/prettier"
+        end,
     }),
 }
 ```
@@ -196,7 +198,7 @@ setting `diagnostics_format`:
 local sources = {
     -- will show code and source name
     null_ls.builtins.diagnostics.shellcheck.with({
-        diagnostics_format = "[#{c}] #{m} (#{s})"
+        diagnostics_format = "[#{c}] #{m} (#{s})",
     }),
 }
 ```
@@ -222,8 +224,7 @@ diagnostic.
 local sources = {
     null_ls.builtins.diagnostics.write_good.with({
         diagnostics_postprocess = function(diagnostic)
-            diagnostic.severity = diagnostic.message:find("really")
-                and vim.diagnostic.severity["ERROR"]
+            diagnostic.severity = diagnostic.message:find("really") and vim.diagnostic.severity["ERROR"]
                 or vim.diagnostic.severity["WARN"]
         end,
     }),
@@ -264,7 +265,7 @@ local sources = {
         cwd = function(params)
             -- falls back to root if return value is nil
             return params.root:match("my-special-project") and "my-special-cwd"
-        end
+        end,
     }),
 }
 ```
@@ -279,7 +280,7 @@ set a different `timeout`:
 local sources = {
     null_ls.builtins.formatting.prettier.with({
         -- milliseconds
-        timeout = 10000
+        timeout = 10000,
     }),
 }
 ```
@@ -303,7 +304,7 @@ to `false`:
 ```lua
 local sources = {
     null_ls.builtins.formatting.phpstan.with({
-        to_temp_file = false
+        to_temp_file = false,
     }),
 }
 ```
@@ -344,7 +345,7 @@ if the command is not available on your `$PATH`:
 ```lua
 local sources = {
     null_ls.builtins.formatting.prettier.with({
-        command = "/path/to/prettier"
+        command = "/path/to/prettier",
     }),
 }
 ```

doc/CONTRIBUTING.md

@@ -31,6 +31,10 @@
   [busted](https://github.com/Olivine-Labs/busted). If you're unsure how to
   write tests for your PR, please let us know and we can help.
 
+- To format Lua code blocks in our Markdown documentation, we recommend
+  [cbfmt](https://github.com/lukas-reineke/cbfmt), which is available as a
+  null-ls built-in.
+
 ## Contributing built-ins
 
 - Check if there is an open issue requesting the built-in you are adding and

doc/MAIN.md

@@ -281,10 +281,12 @@ All return values are **required** unless specified as optional.
 #### Code Actions
 
 ```lua
-return { {
-    title, -- string
-    action, -- function (callback with no arguments)
-} }
+return {
+    {
+        title, -- string
+        action, -- function (callback with no arguments)
+    },
+}
 ```
 
 Once generated, null-ls stores code action results in its internal state and
@@ -298,18 +300,20 @@ safe to call any API function.
 
 ```lua
 -- null-ls assumes ranges are 1-indexed, so sources should offset if not
-return { {
-    row, -- number, optional (defaults to first line)
-    col, -- number, optional (defaults to beginning of line)
-    end_row, -- number, optional (defaults to row)
-    end_col, -- number, optional (defaults to end of line),
-    source, -- string, optional (defaults to "null-ls")
-    code, -- number, optional
-    message, -- string
-    severity, -- 1 (error), 2 (warning), 3 (information), 4 (hint)
-    filename, -- string, optional (requires generator.multiple_files)
-    bufnr, -- number, optional (requires generator.multiple_files)
-} }
+return {
+    {
+        row, -- number, optional (defaults to first line)
+        col, -- number, optional (defaults to beginning of line)
+        end_row, -- number, optional (defaults to row)
+        end_col, -- number, optional (defaults to end of line),
+        source, -- string, optional (defaults to "null-ls")
+        code, -- number, optional
+        message, -- string
+        severity, -- 1 (error), 2 (warning), 3 (information), 4 (hint)
+        filename, -- string, optional (requires generator.multiple_files)
+        bufnr, -- number, optional (requires generator.multiple_files)
+    },
+}
 ```
 
 null-ls generates diagnostics in response to LSP notifications and publishes
@@ -329,13 +333,15 @@ described in [CONFIG](./CONFIG.md).
 #### Formatting
 
 ```lua
-return { {
-    row, -- number, optional (see diagnostics for defaults)
-    col, -- number, optional
-    end_row, -- number, optional
-    end_col, -- number, optional
-    text, -- string
-} }
+return {
+    {
+        row, -- number, optional (see diagnostics for defaults)
+        col, -- number, optional
+        end_row, -- number, optional
+        end_col, -- number, optional
+        text, -- string
+    },
+}
 ```
 
 null-ls applies formatting results to the matching buffer and, depending on the

doc/SOURCES.md

@@ -30,7 +30,7 @@ local example_source = {
             return "I am a source!"
         end,
     },
-    id = 1
+    id = 1,
 }
 ```
 

lua/null-ls/builtins/diagnostics/glslc.lua

@@ -13,12 +13,11 @@ return h.make_builtin({
             [[the `--target-env` can be specified in `extra_args`. Defaults to vulkan1.0. Check `man glslc` for more possible targets environments.]],
         },
         usage = [[
-        local sources = {
-            null_ls.builtins.diagnostics.glslc.with({
-                extra_args = { "--target-env=opengl" } -- use opengl instead of vulkan1.0
-            })
-        }
-        ]],
+local sources = {
+    null_ls.builtins.diagnostics.glslc.with({
+        extra_args = { "--target-env=opengl" }, -- use opengl instead of vulkan1.0
+    }),
+}]],
     },
     method = DIAGNOSTICS,
     filetypes = { "glsl" },

lua/null-ls/builtins/diagnostics/sqlfluff.lua

@@ -11,9 +11,9 @@ return helpers.make_builtin({
         },
         usage = [[
 local sources = {
-	null_ls.builtins.diagnostics.sqlfluff.with({
-		extra_args = {"--dialect", "postgres"} -- change to your dialect
-	})
+    null_ls.builtins.diagnostics.sqlfluff.with({
+        extra_args = { "--dialect", "postgres" }, -- change to your dialect
+    }),
 }]],
     },
     method = null_ls.methods.DIAGNOSTICS,

lua/null-ls/builtins/formatting/sqlfluff.lua

@@ -13,9 +13,9 @@ return h.make_builtin({
         },
         usage = [[
 local sources = {
-	null_ls.builtins.formatting.sqlfluff.with({
-		extra_args = {"--dialect", "postgres"} -- change to your dialect
-	})
+    null_ls.builtins.formatting.sqlfluff.with({
+        extra_args = { "--dialect", "postgres" }, -- change to your dialect
+    }),
 }]],
     },
     method = FORMATTING,