feat: add docs and release please

.github/workflows/lemmy-help.yml

@@ -0,0 +1,25 @@
+name: lemmy-help
+
+on: [push]
+
+env:
+  PLUGIN_NAME: adopure
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: emmylua to vimdoc
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Generating help
+        run: |
+          curl -Lq https://github.com/numToStr/lemmy-help/releases/latest/download/lemmy-help-x86_64-unknown-linux-gnu.tar.gz | tar xz
+          ./lemmy-help [args] <path> > doc/${{env.PLUGIN_NAME}}.txt
+
+      - name: Commit
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          branch: ${{ github.head_ref }}
+          commit_message: "chore(docs): auto-generate vimdoc"
+          file_pattern: doc/*.txt

.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: google-github-actions/release-please-action@v3
+        with:
+          token: ${{ secrets.PAT }}
+          release-type: simple
+          package-name: AdoPure

doc/adopure.txt

@@ -0,0 +1,102 @@
+==============================================================================
+Table of Contents                                                      *adopure*
+
+ ····································································· |adopure|
+ ························································· |adopure.config.meta|
+
+==============================================================================
+                                                                       *adopure*
+
+The plugin provides an opinionated worfklow to interact with Azure DevOps Pull Requests.
+
+M.ado_pure({opts})                                                  *M.ado_pure*
+    Main nvim command line entry point of the plugin.
+    Intended to be called using the command: AdoPure.
+    The command is autocompleting when used in neovim command line. Valid options include:
+
+    :AdoPure [ load ] [ context | threads ] [ opts ]
+         Loads specified into state.
+
+             *context*: load open pull requests; prompt user to pick one.
+             Note: Subsequent commands will operate on the chosen PR.
+
+             *threads*: Fetch comment threads from Azure DevOps.
+
+
+    :AdoPure [ open ] [ quickfix | thread_picker | new_thread | existing_thread ] [ opts ]
+         Opens specified in the editor.
+
+             *quickfix*: Open comment threads in quickfix window.
+
+             *thread_picker*: Open a picker with all comment threads.
+             Supports filtering like so:
+                 :AdoPure open thread_picker {thread_filters={'hide_system', 'hide_closed'}}
+
+             *new_thread*: Opens a window to write a comment on code selection.
+
+             *existing_thread*: Opens a window with an existing comment thread.
+
+
+    :AdoPure [ submit ] [ comment | vote | thread_status ] [ opts ]
+         Submits specified to Azure DevOps.
+
+             *comment*: Submit new comment or reply; must be in new_thread or existing_thread window.
+
+             *vote*: Submit a new vote on the pull request.
+
+             *thread_status*: Submit a thread_status change; must be in existing_thread window.
+
+    Note: If no arguments args provided, the user will be prompted.
+
+    Parameters: ~
+        {opts}  (table)  provided by neovim user command context.
+
+    Usage: ~
+>lua
+        vim.cmd(':AdoPure load context {}')
+<
+
+
+M.load_state_manager()                                    *M.load_state_manager*
+    Initialize state_manager, contains repository and all open pull requests.
+    If not using the vim command line interface, call this first.
+
+    Returns: ~
+        (adopure.StateManager)
+
+
+M.get_loaded_state()                                        *M.get_loaded_state*
+    Return state of the plugin; raises if no pull request has been loaded into context.
+    If not using the vim command line interface, call this to get state required for the other commands.
+
+    Returns: ~
+        (adopure.AdoState)
+
+
+==============================================================================
+                                                           *adopure.config.meta*
+
+adopure.Highlights                                          *adopure.Highlights*
+    The plugin is configured by setting vim.g.adopure.
+
+    `@type adopure.Config
+    vim.g.adopure = { pat_token = secret_value }
+
+
+
+    Fields: ~
+        {active?}         (string)  Highlight for lines with active comments.
+        {active_sign?}    (string)  Highlight for sign indicating active comments.
+        {inactive?}       (string)  Highlight for lines with inactive comments.
+        {inactive_sign?}  (string)  Highlight for sign indicating in active comments.
+
+
+adopure.Config                                                  *adopure.Config*
+
+    Fields: ~
+        {pat_token?}          (string)              Personal Access Token to acess Azure DevOps.
+        {hl_groups?}          (adopure.Highlights)  Highlight groups to apply.
+        {preferred_remotes?}  (string[])            List with preferred remotes to extract Azure DevOps context from.
+
+
+vim:tw=78:ts=8:noet:ft=help:norl:

lua/adopure.lua

@@ -1,12 +1,14 @@
+---@toc adopure
+---@mod adopure
+
+---@brief [[
+---The plugin provides an opinionated worfklow to interact with Azure DevOps Pull Requests.
+---@brief ]]
+
 local M = {}
 
 ---@type adopure.StateManager|nil
 local state_manager
----@return adopure.AdoState
-function M.get_loaded_state()
-    assert(state_manager and state_manager.state, "Choose and activate a pull request first;")
-    return state_manager.state
-end
 
 local function completer(load_args, arg_lead)
     return vim.iter(load_args)
@@ -37,21 +39,11 @@ local function execute_or_prompt(sub_impl, subcommand_args, subcommand)
     sub_impl[subcommand_args[1]](ok and opts or {})
 end
 
+---@private
 ---@class adopure.SubCommand
 ---@field impl fun(args:string[])
 ---@field complete_args? string[]
 
----Initial load of state_manager with all open PRs;
----@return adopure.StateManager
-function M.load_state_manager()
-    if not state_manager then
-        local context = require("adopure.state").AdoContext:new()
-        state_manager = require("adopure.state").StateManager:new(context)
-    end
-    assert(state_manager, "StateManager should not be nil after loading;")
-    return state_manager
-end
-
 ---@type table<string, adopure.SubCommand>
 local subcommand_tbl = {
     load = {
@@ -108,7 +100,47 @@ local subcommand_tbl = {
     },
 }
 
----@param opts table
+---Main nvim command line entry point of the plugin.
+---Intended to be called using the command: AdoPure.
+---The command is autocompleting when used in neovim command line. Valid options include:
+---
+---:AdoPure [ load ] [ context | threads ] [ opts ]
+---     Loads specified into state.
+---
+---         *context*: load open pull requests; prompt user to pick one.
+---         Note: Subsequent commands will operate on the chosen PR.
+---
+---         *threads*: Fetch comment threads from Azure DevOps.
+---
+---
+---:AdoPure [ open ] [ quickfix | thread_picker | new_thread | existing_thread ] [ opts ]
+---     Opens specified in the editor.
+---
+---         *quickfix*: Open comment threads in quickfix window.
+---
+---         *thread_picker*: Open a picker with all comment threads.
+---         Supports filtering like so:
+---             :AdoPure open thread_picker {thread_filters={'hide_system', 'hide_closed'}}
+---
+---         *new_thread*: Opens a window to write a comment on code selection.
+---
+---         *existing_thread*: Opens a window with an existing comment thread.
+---
+---
+---:AdoPure [ submit ] [ comment | vote | thread_status ] [ opts ]
+---     Submits specified to Azure DevOps.
+---
+---         *comment*: Submit new comment or reply; must be in new_thread or existing_thread window.
+---
+---         *vote*: Submit a new vote on the pull request.
+---
+---         *thread_status*: Submit a thread_status change; must be in existing_thread window.
+---
+---Note: If no arguments args provided, the user will be prompted.
+---@param opts table provided by neovim user command context.
+---@usage lua [[
+---vim.cmd(':AdoPure load context {}')
+---@usage ]]
 function M.ado_pure(opts)
     local fargs = opts.fargs
     local subcommand_key = fargs[1]
@@ -130,6 +162,27 @@ function M.ado_pure(opts)
     subcommand.impl(args)
 end
 
+---Initialize state_manager, contains repository and all open pull requests.
+---If not using the vim command line interface, call this first.
+---@return adopure.StateManager
+function M.load_state_manager()
+    if not state_manager then
+        local context = require("adopure.state").AdoContext:new()
+        state_manager = require("adopure.state").StateManager:new(context)
+    end
+    assert(state_manager, "StateManager should not be nil after loading;")
+    return state_manager
+end
+
+---Return state of the plugin; raises if no pull request has been loaded into context.
+---If not using the vim command line interface, call this to get state required for the other commands.
+---@return adopure.AdoState
+function M.get_loaded_state()
+    assert(state_manager and state_manager.state, "Choose and activate a pull request first;")
+    return state_manager.state
+end
+
+---@private
 function M.auto_completer(arg_lead, cmdline, _)
     local subcmd_key, subcmd_arg_lead = cmdline:match("^'?<?,?'?>?AdoPure*%s(%S+)%s(.*)$")
     if subcmd_key and subcmd_arg_lead and subcommand_tbl[subcmd_key] and subcommand_tbl[subcmd_key].complete_args then

lua/adopure/config/meta.lua

@@ -1,13 +1,21 @@
+---@mod adopure.config.meta
+
+---The plugin is configured by setting vim.g.adopure.
+---
+---`@type adopure.Config
+---vim.g.adopure = { pat_token = secret_value }
+---
+---
 ---@class adopure.Highlights
----@field active? string
----@field active_sign? string
----@field inactive? string
----@field inactive_sign? string
+---@field active? string Highlight for lines with active comments.
+---@field active_sign? string Highlight for sign indicating active comments.
+---@field inactive? string Highlight for lines with inactive comments.
+---@field inactive_sign? string Highlight for sign indicating in active comments.
 
 ---@class adopure.Config
----@field pat_token? string
----@field hl_groups? adopure.Highlights
----@field preferred_remotes? string[]
+---@field pat_token? string Personal Access Token to acess Azure DevOps.
+---@field hl_groups? adopure.Highlights Highlight groups to apply.
+---@field preferred_remotes? string[] List with preferred remotes to extract Azure DevOps context from.
 
 local config = {}