docs(sync): update vimdoc for backend interface

Problem: Vimdoc documents :Pending sync as a bare command that pushes
to Google Calendar, with no mention of backends or the sync table config.

Solution: Update :Pending sync section to show {backend} [{action}]
syntax with examples, add SYNC BACKENDS section documenting the interface
contract, update config example to use sync.gcal, document legacy gcal
migration, and update health check description.
This commit is contained in:
Barrett Ruth 2026-02-26 16:44:30 -05:00
parent 7de9c23ec1
commit 23d34addc8

View file

@ -47,7 +47,7 @@ REQUIREMENTS *pending-requirements*
- Neovim 0.10+ - Neovim 0.10+
- No external dependencies for local use - No external dependencies for local use
- `curl` and `openssl` are required for Google Calendar sync - `curl` and `openssl` are required for the `gcal` sync backend
============================================================================== ==============================================================================
INSTALL *pending-install* INSTALL *pending-install*
@ -250,10 +250,23 @@ COMMANDS *pending-commands*
Open the list with |:copen| to navigate to each task's category. Open the list with |:copen| to navigate to each task's category.
*:Pending-sync* *:Pending-sync*
:Pending sync :Pending sync {backend} [{action}]
Push pending tasks that have a due date to Google Calendar as all-day Run a sync action against a named backend. {backend} is required — bare
events. Requires |pending-gcal| to be configured. See |pending-gcal| for `:Pending sync` prints a usage message. {action} defaults to `sync`
full details on what gets created, updated, and deleted. when omitted. Each backend lives at `lua/pending/sync/<name>.lua`.
Examples: >vim
:Pending sync gcal " runs gcal.sync()
:Pending sync gcal auth " runs gcal.auth()
:Pending sync gcal sync " explicit sync (same as bare)
<
Tab completion after `:Pending sync ` lists discovered backends.
Tab completion after `:Pending sync gcal ` lists available actions.
Built-in backends: ~
`gcal` Google Calendar one-way push. See |pending-gcal|.
*:Pending-undo* *:Pending-undo*
:Pending undo :Pending undo
@ -440,9 +453,11 @@ loads: >lua
next_task = ']t', next_task = ']t',
prev_task = '[t', prev_task = '[t',
}, },
gcal = { sync = {
calendar = 'Tasks', gcal = {
credentials_path = '/path/to/client_secret.json', calendar = 'Tasks',
credentials_path = '/path/to/client_secret.json',
},
}, },
} }
< <
@ -508,10 +523,16 @@ Fields: ~
vim.g.pending = { debug = true } vim.g.pending = { debug = true }
< <
{sync} (table, default: {}) *pending.SyncConfig*
Sync backend configuration. Each key is a backend
name and the value is the backend-specific config
table. Currently only `gcal` is built-in.
{gcal} (table, default: nil) {gcal} (table, default: nil)
Google Calendar sync configuration. See Legacy shorthand for `sync.gcal`. If `gcal` is set
|pending.GcalConfig|. Omit this field entirely to but `sync.gcal` is not, the value is migrated
disable Google Calendar sync. automatically. New configs should use `sync.gcal`
instead. See |pending.GcalConfig|.
============================================================================== ==============================================================================
LUA API *pending-api* LUA API *pending-api*
@ -632,13 +653,18 @@ not pulled back into pending.nvim.
Configuration: >lua Configuration: >lua
vim.g.pending = { vim.g.pending = {
gcal = { sync = {
calendar = 'Tasks', gcal = {
credentials_path = '/path/to/client_secret.json', calendar = 'Tasks',
credentials_path = '/path/to/client_secret.json',
},
}, },
} }
< <
The legacy `gcal` top-level key is still accepted and migrated automatically.
New configurations should use `sync.gcal`.
*pending.GcalConfig* *pending.GcalConfig*
Fields: ~ Fields: ~
{calendar} (string, default: 'Pendings') {calendar} (string, default: 'Pendings')
@ -654,7 +680,7 @@ Fields: ~
that Google provides or as a bare credentials object. that Google provides or as a bare credentials object.
OAuth flow: ~ OAuth flow: ~
On the first `:Pending sync` call the plugin detects that no refresh token On the first `:Pending sync gcal` call the plugin detects that no refresh token
exists and opens the Google authorization URL in the browser using exists and opens the Google authorization URL in the browser using
|vim.ui.open()|. A temporary local HTTP server listens on port 18392 for the |vim.ui.open()|. A temporary local HTTP server listens on port 18392 for the
OAuth redirect. The PKCE (Proof Key for Code Exchange) flow is used — OAuth redirect. The PKCE (Proof Key for Code Exchange) flow is used —
@ -664,7 +690,7 @@ authorization code is exchanged for tokens and the refresh token is stored at
use the stored refresh token and refresh the access token automatically when use the stored refresh token and refresh the access token automatically when
it is about to expire. it is about to expire.
`:Pending sync` behavior: ~ `:Pending sync gcal` behavior: ~
For each task in the store: For each task in the store:
- A pending task with a due date and no existing event: a new all-day event is - A pending task with a due date and no existing event: a new all-day event is
created and the event ID is stored in the task's `_extra` table. created and the event ID is stored in the task's `_extra` table.
@ -677,6 +703,30 @@ For each task in the store:
A summary notification is shown after sync: `created: N, updated: N, A summary notification is shown after sync: `created: N, updated: N,
deleted: N`. deleted: N`.
==============================================================================
SYNC BACKENDS *pending-sync-backend*
Sync backends are Lua modules under `lua/pending/sync/<name>.lua`. Each
module returns a table conforming to the backend interface: >lua
---@class pending.SyncBackend
---@field name string
---@field auth fun(): nil
---@field sync fun(): nil
---@field health? fun(): nil
<
Required fields: ~
{name} Backend identifier (matches the filename).
{sync} Main sync action. Called by `:Pending sync <name>`.
{auth} Authorization flow. Called by `:Pending sync <name> auth`.
Optional fields: ~
{health} Called by `:checkhealth pending` to report backend-specific
diagnostics (e.g. checking for external tools).
Backend-specific configuration goes under `sync.<name>` in |pending-config|.
============================================================================== ==============================================================================
HIGHLIGHT GROUPS *pending-highlights* HIGHLIGHT GROUPS *pending-highlights*
@ -728,8 +778,8 @@ Checks performed: ~
- Whether the data directory exists (warning if not yet created) - Whether the data directory exists (warning if not yet created)
- Whether the data file exists and can be parsed; reports total task count - Whether the data file exists and can be parsed; reports total task count
- Validates recurrence specs on stored tasks - Validates recurrence specs on stored tasks
- Whether `curl` is available (required for Google Calendar sync) - Discovers sync backends under `lua/pending/sync/` and runs each backend's
- Whether `openssl` is available (required for OAuth PKCE) `health()` function if it exists (e.g. gcal checks for `curl` and `openssl`)
============================================================================== ==============================================================================
DATA FORMAT *pending-data* DATA FORMAT *pending-data*