docs: add basic docs

README.md

@@ -1,52 +1,90 @@
- <!-- LTeX: enabled=false -->
+<!-- LTeX: enabled=false -->
 # nvim-rule-breaker <!-- LTeX: enabled=true -->
 <!-- TODO uncomment shields when available in dotfyle.com -->
 <!-- <a href="https://dotfyle.com/plugins/chrisgrieser/nvim-rule-breaker"><img src="https://dotfyle.com/plugins/chrisgrieser/nvim-rule-breaker/shield" /></a> -->
 
 Add inline-comments to locally disable diagnostic rules.
 
+Most LSPs provide code actions for to do that – this plugin adds commands for linters and LSPs that don't. (As such, this plugin is partially a replacement for [null-ls](https://github.com/jose-elias-alvarez/null-ls.nvim/)'s code action feature.)
+
 <!--toc:start-->
 - [Features](#features)
+- [Supported Linters for adding ignore-comments](#supported-linters-for-adding-ignore-comments)
 - [Installation](#installation)
 - [Configuration](#configuration)
-- [Limitations](#limitations)
 - [Credits](#credits)
 <!--toc:end-->
 
 ## Features
+- Add inline-comments that ignore diagnostic rules.
+- Location of the ignore comment, like next line or previous line, is configurable.
+- Perform a web search for a diagnostic rule.
+- Requires diagnostics provided by a source that supports neovim's builtin diagnostics system (`vim.diagnostic`). nvim's builtin LSP client and [nvim-lint](https://github.com/mfussenegger/nvim-lint) are such sources.
+
+## Supported Linters for adding ignore-comments
+<!-- list-of-supported-linters start -->
+- selene
+- shellcheck
+- vale
+- yamllint
+- stylelint
+- LTeX
+<!-- list-of-supported-linters end -->
+
+You easily add a custom via the [plugin configuration](#configuration). However, please consider making a PR to add support for a linter if it is missing.
+
+[Ignore Rule Data for the supported linters](./lua/rule-breaker/ignoreRuleData.lua)
 
 ## Installation
 
 ```lua
 -- lazy.nvim
 {
 	"chrisgrieser/nvim-rule-breaker",
-	opts = {
-
-	},
+	keys = {
+		{ "<leader>i", function() require("rule-breaker").ignoreRule() end },
+		{ "<leader>l", function() require("rule-breaker").lookupRule() end },
+	}
 },
+```
 
+```lua
 -- packer
-use {
-	"chrisgrieser/nvim-rule-breaker",
-	config = function () 
-		require("rule-breaker").setup ({
-
-		})
-	end,
-}
+use { "chrisgrieser/nvim-rule-breaker" }
+
+-- in your config
+vim.keymap.set("n", "<leader>i", function() require("rule-breaker").ignoreRule() end)
+vim.keymap.set("n", "<leader>l", function() require("rule-breaker").lookupRule() end)
 ```
 
 ## Configuration
 
 ```lua
--- default values
-opts = {
+defaultConfig = {
+	ignoreRuleComments = {
+		selene = {
+			comment = "-- selene: allow(%s)",
+			location = "prevLine",
+		},
+		-- full list of builtin-linters found in README
+		yourLinter = {
+			-- %s will be replaced with rule-id
+			-- if location is "encloseLine", needs to be a list of two strings
+			comment = "// disabling-comment %s",
+
+			-- "prevLine"|"sameLine"|"encloseLine"
+			location = "prevLine",
+		}
+	},
 
+	-- searchUrl for rule lookup. Default is the DuckDuckGo 
+	-- "Ducky Search" (automatically opening first result)
+	searchUrl = "https://duckduckgo.com/?q=%s+%%21ducky&kl=en-us",
 }
 ```
 
-## Limitations
+> [!NOTE]
+> The plugin uses `vim.ui.select()`, so the appearance of the rule selection can be customized by using a ui-plugin like [dressing.nvim](https://github.com/stevearc/dressing.nvim).
 
 ## Credits
 <!-- vale Google.FirstPerson = NO -->

lua/rule-breaker/ignoreRuleData.lua

@@ -1,32 +1,45 @@
 ---@class ruleIgnoreConfig
 ---@field comment string|string[] with %s for the rule id
----@field location "sameLine"|"nextLine"|"encloseLine"
+---@field location "sameLine"|"prevLine"|"encloseLine"
+---@field docs string
 
 -- INFO "encloseLine" is a list with two strings, one to be inserted before and
--- one to be inserted after. (nextLine or sameLine comments are obviously
+-- one to be inserted after. (prevLine or sameLine comments are obviously
 -- preferred, but some linters to do support that.)
 
 ---@type table<string, ruleIgnoreConfig>
 local data = {
 	shellcheck = {
 		comment = "# shellcheck disable=%s",
-		location = "nextLine",
+		location = "prevLine",
+		docs = "https://www.shellcheck.net/wiki/Ignore",
 	},
 	selene = {
 		comment = "-- selene: allow(%s)",
-		location = "nextLine",
-	},
-	vale = {
-		comment = { "<!-- vale %s = NO -->", "<!-- vale %s = YES -->" },
-		location = "encloseLine",
+		location = "prevLine",
+		docs = "https://kampfkarren.github.io/selene/usage/filtering.html#allowingdenying-lints-for-an-entire-file",
 	},
 	yamllint = {
 		comment = "# yamllint disable-line rule:%s",
-		location = "nextLine",
+		location = "prevLine",
+		docs = "https://yamllint.readthedocs.io/en/stable/disable_with_comments.html",
 	},
 	stylelint = {
 		comment = "/* stylelint-disable-next-line %s */",
-		location = "nextLine",
+		location = "prevLine",
+		docs = "https://stylelint.io/user-guide/ignore-code/",
+	},
+	LTeX = {
+		-- ltex does not allow disabling individual rules, so it has to be
+		-- enabled/disables completely
+		comment = { "<!-- LTeX: enabled=false -->", "<!-- LTeX: enabled=true -->" },
+		location = "encloseLine",
+		docs = "https://valentjn.github.io/ltex/advanced-usage.html",
+	},
+	vale = {
+		comment = { "<!-- vale %s = NO -->", "<!-- vale %s = YES -->" },
+		location = "encloseLine",
+		docs = "https://vale.sh/docs/topics/config/#markup-based-configuration",
 	},
 }
 

lua/rule-breaker/init.lua

@@ -32,11 +32,12 @@ end
 ---@param diag diagnostic
 ---@return boolean whether rule is valid
 local function validDiagObj(diag)
+	local issuePlea = "\nPlease open an issue at the plugin that provides the diagnostics."
 	if not diag.code then
-		notify("Diagnostic is missing a code (rule id)", "warn")
+		notify("Diagnostic is missing a code (rule id). " .. issuePlea, "warn")
 		return false
 	elseif not diag.source then
-		notify("Diagnostic is missing a source", "warn")
+		notify("Diagnostic is missing a source" .. issuePlea, "warn")
 		return false
 	end
 	return true
@@ -81,7 +82,7 @@ local function addIgnoreComment(diag)
 
 	-- insert the comment
 	local ignoreLocation = ignoreRuleData[diag.source].location
-	if ignoreLocation == "nextLine" then
+	if ignoreLocation == "prevLine" then
 		local prevLineNum = vim.api.nvim_win_get_cursor(0)[1] - 1
 		vim.api.nvim_buf_set_lines(0, prevLineNum, prevLineNum, false, ignoreComment)
 	elseif ignoreLocation == "sameLine" then