From 213b1f7409b18a44988501b7dbae01381c49547c Mon Sep 17 00:00:00 2001 From: Harrison Cramer Date: Mon, 13 Nov 2023 09:24:22 -0500 Subject: [PATCH] README updates Adds table of contents and shortens diagnostic section to most valuable information --- README.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 40716ef4..28a81c3a 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,28 @@ And a lot more! https://github.com/harrisoncramer/gitlab.nvim/assets/32515581/50f44eaf-5f99-4cb3-93e9-ed66ace0f675 +## Table of Contents + +[Requirements](#requirements) +[Quick Start](#quick-start) +[Installation](#installation) +[Connecting to Gitlab](#connecting-to-gitlab) +[Configuring the Plugin](#configuring-the-plugin) +[Usage](#usage) +- [The summary command](#summary) +- [Reviewing Diffs](#reviewing-diffs) +- [Discussions and Notes](#discussions-and-notes) +- [Discussion signs and diagnostics](#discussion-signs-and-diagnostics) +- [Discussion signs and diagnostics](#discussion-signs-and-diagnostics) +- [Uploading Files](#uploading-files) +- [MR Approvals](#mr-approvals) +- [Pipelines](#pipelines) +- [Reviewers and Assignees](#reviewers-and-assignees) +[Keybindings](#keybindings) +[Troubleshooting](#troubleshooting) +[Extras](#extra-goodies) + + ## Requirements - Go >= v1.19 @@ -64,7 +86,7 @@ use { } ``` -## Project Configuration +## Connecting to Gitlab This plugin requires an auth token to connect to Gitlab. The token can be set in the root directory of the project in a `.gitlab.nvim` environment file, or can be set via a shell environment variable called `GITLAB_TOKEN` instead. If both are present, the `.gitlab.nvim` file will take precedence. @@ -218,7 +240,7 @@ If you'd like to create a note in an MR (like a comment, but not linked to a spe require("gitlab").create_note() ``` -### Discussions signs and diagnostics +### Discussion signs and diagnostics By default when reviewing files you will see signs and diagnostics ( if enabled in configuration ). When cursor is on diagnostic line you can view discussion thread by using `vim.diagnostic.show`. You can also jump to discussion tree where you can reply, edit or delete discussion. @@ -226,9 +248,9 @@ By default when reviewing files you will see signs and diagnostics ( if enabled require("gitlab").move_to_discussion_tree_from_diagnostic() ``` -The `discussion_sign` configuration controls the display of signs for discussions. The `enabled` option turns on/off the signs. `text` sets the sign text. `linehl`, `texthl`, `culhl`, and `numhl` customize the line highlighting, text highlighting, column highlighting, and number highlighting respectively. Keep in mind that these can be overridden by other configuration (for example diffview.nvim highlights). `priority` controls the sign priority order (when multiple signs are placed on the same line, the sign with highest priority is used). The `helper_signs` table configures additional signs for multiline discussions in order to show the whole context. `enabled` turns on/off the helper signs. `start`, `mid`, and `end` set the helper sign text. +The `discussion_sign` configuration controls the display of signs for discussions in the reviewer pane. Keep in mind that the highlights provided here can be overridden by other highlights (for example from diffview.nvim). The `priority` setting controls the sign priority order (when multiple signs are placed on the same line, the sign with highest priority is used). The `helper_signs` table configures additional signs for multiline discussions in order to show the whole context. -The `discussion_diagnostic` configuration customizes the diagnostic display for discussions. The `enabled` option turns on/off the diagnostics. `severity` sets the diagnostic severity level and should be set to one of `vim.diagnostic.severity.ERROR`, `vim.diagnostic.severity.WARN`, or `vim.diagnostic.severity.INFO`, `vim.diagnostic.severity.HINT`. `code` specifies a diagnostic code. `display_opts` configures the diagnostic display options where you can configure values like (this is dirrectly used as opts in vim.diagnostic.set): +The `discussion_diagnostic` configuration customizes the diagnostic display for discussions. The `severity` key sets the diagnostic severity level and should be set to one of `vim.diagnostic.severity.ERROR`, `vim.diagnostic.severity.WARN`, `vim.diagnostic.severity.INFO`, or `vim.diagnostic.severity.HINT`. The `display_opts` option configures the diagnostic display options where you can configure values like (this is dirrectly used as opts in vim.diagnostic.set): - `virtual_text` - Show virtual text for diagnostics. - `underline` - Underline text for diagnostics. @@ -240,9 +262,7 @@ Signs and diagnostics have common settings in `discussion_sign_and_diagnostics`. - `skip_resolved_discussion` - Whether to skip showing signs and diagnostics for resolved discussions. Default is `false`, meaning signs and diagnostics will be shown for resolved discussions. - `skip_old_revision_discussion` - Whether to skip showing signs and diagnostics for discussions on outdated diff revisions. Default is `true`, meaning signs and diagnostics won't be shown for discussions no longer relevant to the current diff. -#### Limitations - -When checking multiline diagnostic the cursor must be on the "main" line of diagnostic -> where the `discussion_sign.text` is shown otherwise `vim.diagnostic.show` and `jump_to_discussion_tree_from_diagnostic` will not work. +When interacting with multiline comments, the cursor must be on the "main" line of diagnostic, where the `discussion_sign.text` is shown, otherwise `vim.diagnostic.show` and `jump_to_discussion_tree_from_diagnostic` will not work. ### Uploading Files