Switch over to documentation generation

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: autogen-docs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: generate docs
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - if: github.event_name == 'pull_request'
+        run: git fetch --no-tags --depth=1 origin master
+      - name: panvimdoc
+        uses: kdheepak/panvimdoc@v4.0.0
+        with:
+          vimdoc: decipher
+          pandoc: "README.md"
+          version: "NVIM >= v0.8.0"
+          toc: false
+          description: "A plugin that provides ways to encode and decode text using various codecs like base64."
+          demojify: false
+          dedupsubheadings: true
+          treesitter: true
+          ignorerawblocks: true
+          docmapping: false
+          docmappingprojectname: true
+          shiftheadinglevelby: 0
+          incrementheadinglevelby: 0
+      - name: preview changes
+        if: github.event_name == 'pull_request'
+        run: |
+          git diff --color=always origin/master -- "doc/decipher.txt"
+          cat "doc/decipher.txt"
+      - uses: stefanzweifel/git-auto-commit-action@v6
+        if: github.ref == 'refs/heads/master'
+        with:
+          commit_message: "Auto-generate docs"
+          commit_user_name: "github-actions[bot]"
+          commit_user_email: "github-actions[bot]@users.noreply.github.com"
+          commit_author: "github-actions[bot] <github-actions[bot]@users.noreply.github.com>"

API.md

@@ -0,0 +1,133 @@
+# API
+
+Below is the specification for the public types and api functions.
+
+## Types
+
+## `decipher.Codecs`
+
+Type: ```lua
+enum
+```
+
+Values:
+
+* `base32`
+* `base64`
+* `base64_url`
+* `base64_url_encoded`
+* `base64_url_safe`
+* `crockford`
+* `c_escape`
+* `url`
+* `url_plus`
+* `xml`
+* `zbase32`
+
+## `decipher.CodecArg`
+
+Type: ```lua
+string | decipher.Codecs
+```
+
+General type for functions that accept codecs as arguments. Either a string
+(e.g. "base64") or or a an enum (e.g. decipher.codec.base64).
+
+## API functions
+
+Any functions not listed here that may be accessed via the decipher module are
+not considered public and are subject to change.
+
+### `decipher.setup({config})`
+
+Setup global configuration for decipher. See [`decipher.setup`](#decipher-setup)
+
+Parameters:  
+    • {config} (`decipher.Config`) Setup configuration table
+
+### `decipher.version()`
+
+Returns the current version string.
+
+### `decipher.supported_codecs()`
+
+Returns a list of currently supported codecs.
+
+Return:
+    (type) ...
+
+### `decipher.encode({codec_name}, {value})`
+
+Encode a value using a codec.
+
+Parameters:  
+    • {codec_name} (`decipher.CodecArg`) Setup configuration table
+    • {value}      (`string`) Value to encode
+
+### `decipher.decode({codec_name}, {value})`
+
+Decode a value using a codec.
+
+### `decipher.encode_selection({codec_name}, {options})`
+
+Encode a visual selection using a codec.
+
+Parameters:  
+    • {codec_name} (`decipher.CodecArg`) Codec to use for encoding
+    • {options}    (`decipher.Options`) Options to use
+
+### `decipher.decode_selection({codec_name}, {options})`
+
+Decode a visual selection using a codec.
+
+Parameters:  
+    • {codec_name} (`decipher.CodecArg`) Codec to use for decoding
+    • {options}    (`decipher.Options`) Options to use
+
+### `decipher.encode_motion({codec_name}, {options})`
+
+Encode using a motion and a codec.
+
+Parameters:  
+    • {codec_name} (`decipher.CodecArg`) Codec to use for encoding
+    • {options}    (`decipher.Options`) Options to use
+
+### `decipher.decode_motion({codec_name}, {options})`
+
+Decode using a motion and a codec.
+
+Parameters:  
+    • {codec_name} (`decipher.CodecArg`) Codec to use for decoding
+    • {options}    (`decipher.Options`) Options to use
+
+### `decipher.encode_selection_prompt({options})`
+
+Encode a visual selection using a codec. Prompts with a list of the active
+codecs via `vim.ui.select`.
+
+Parameters:  
+    • {options} (`decipher.Options`) Options to use
+
+### `decipher.decode_selection_prompt({options})`
+
+Decode a visual selection using a codec. Prompts with a list of the active
+codecs via `vim.ui.select`.
+
+Parameters:  
+    • {options} (`decipher.Options`) Options to use
+
+### `decipher.encode_motion_prompt({options})`
+
+Encode using a motion. Prompts with a list of the active codecs via
+`vim.ui.select`.
+
+Parameters:  
+    • {options}    (`decipher.Options`) Options to use
+
+### `decipher.decode_motion_prompt({options})`
+
+Decode using a motion. Prompts with a list of the active codecs via
+vim.ui.select.
+
+Parameters:  
+    • {options}    (`decipher.Options`) Options to use

README.md

@@ -10,50 +10,40 @@
   <br />
 </div>
 
-> [!IMPORTANT]  
-> A bit library is needed which requires that either neovim has been compiled with luajit or you are using v0.9.0+ which provides a bit library.
-
 ![demo](https://github.com/MisanthropicBit/decipher.nvim/assets/1846147/6bc4db76-9a3b-428b-99b4-98e56d06901e)
 
 # Table of contents
 
 - [Installing](#installing)
 - [Setup](#setup)
+- [JSON view](#json-view)
 - [Example keymaps](#example-keymaps)
+- [Encode/decode text-objects](#encode-decode-text-objects)
+- [Highlights](#highlights)
 - [Supported Codecs](#supported-codecs)
-    - [base32](#base32)
-    - [base64](#base64)
-    - [base64-url](#base64-url)
-    - [base64-url-safe](#base64)
-    - [base64-url-encoded](#base64-url-encoded)
-    - [crockford](#crockford)
-    - [c-escape](#c-escape)
-    - [url](#url)
-    - [url-plus](#url-plus)
-    - [xml](#xml)
-    - [z-base32](#z-base32)
+    - [Base32](#base32)
+    - [Base64](#base64)
+    - [Base64-url](#base64-url)
+    - [Base64-url-safe](#base64)
+    - [Base64-url-encoded](#base64-url-encoded)
+    - [Crockford](#crockford)
+    - [C-escape](#c-escape)
+    - [Url](#url)
+    - [Url-plus](#url-plus)
+    - [Xml](#xml)
+    - [Z-base32](#z-base32)
 
 ## Installing
 
-Requires at least neovim v0.8.0. Please check the [docs](doc/decipher.txt).
-
-* **[vim-plug](https://github.com/junegunn/vim-plug)**
-
-```vim
-Plug 'MisanthropicBit/decipher.nvim'
-```
+> [!IMPORTANT]  
+> A bit library is needed which requires that either neovim has been compiled with luajit or you are using v0.9.0+ which provides a bit library.
 
-* **[packer.nvim](https://github.com/wbthomason/packer.nvim)**
-
-```lua
-use 'MisanthropicBit/decipher.nvim'
-```
+Requires at least neovim v0.8.0.
 
 ## Setup
 
 Setup decipher using `decipher.setup` unless you are content with the defaults.
-The options below are the default values. Refer to the
-[docs](doc/decipher.txt) for more help.
+The options below are the default values.
 
 ```lua
 require("decipher").setup({
@@ -126,7 +116,7 @@ normal view instead.
 ## Example keymaps
 
 There are several ways in which you can invoke `decipher`. Check out the
-[docs](doc/decipher.txt) for the full api. Below are some examples:
+[API docs](API.md) for more information. Below are some examples:
 
 ```lua
 -- Encode visually selected text as base64. If invoked from normal mode it will
@@ -141,6 +131,32 @@ vim.keymap.set("n", "<mykeymap>", function()
 end)
 ```
 
+## Encode/decode text-objects
+
+Decipher can encode and decode text-objects. The following `lua` code sets up
+`decipher` to decode a text-object using base64 using a floating window preview.
+Check out the [API docs](API.md) for more information
+
+```lua
+    local decipher = require("decipher")
+
+    vim.keymap.set(
+        "n",
+        "<leader>d",
+        function()
+            decipher.decode_motion("base64", { preview = true })
+        end,
+        { noremap = true, silent = true }
+    )
+```
+
+## Highlights
+
+### `DecipherFloatTitle`
+
+Highlight group for the title of the floating window preview. Defaults to
+`Title`.
+
 ## Supported Codecs
 
 #### Base32