Add reference material for plugin module

Addresses wez#6177

ci/generate-docs.py

@@ -393,6 +393,10 @@ def render(self, output, depth=0, mode="mdbook"):
                 "module: wezterm.mux",
                 "config/lua/wezterm.mux",
             ),
+            Gen(
+                "module: wezterm.plugin",
+                "config/lua/wezterm.plugin",
+            ),
             Gen(
                 "module: wezterm.procinfo",
                 "config/lua/wezterm.procinfo",

docs/config/lua/wezterm.plugin/index.markdown

@@ -0,0 +1,7 @@
+# `wezterm.plugin` module
+
+{{since('20230320-124340-559cb7b0')}}
+
+The `wezterm.plugin` module provides functions to manage Wezterm plugins.
+
+## Available functions

docs/config/lua/wezterm.plugin/index.md

@@ -0,0 +1,12 @@
+# `wezterm.plugin` module
+
+{{since('20230320-124340-559cb7b0')}}
+
+The `wezterm.plugin` module provides functions to manage Wezterm plugins.
+
+## Available functions
+
+
+  - [list](list.md)
+  - [require](require.md)
+  - [update_all](update_all.md)

docs/config/lua/wezterm.plugin/list.md

@@ -0,0 +1,11 @@
+# list function
+
+{{since('20230320-124340-559cb7b0')}}
+
+Will return a table array listing all the plugin repos in the plugin directory
+
+Each entry has three fields:
+
+* `url`: The URL of the plugin repo, as provided to the `wezterm.plugin.require` function
+* `component`: The encoded name of the plugin, derived from the repo URL
+* `plugin_dir`: The absolute location of the plugin checkout in the Wexterm runtime directory. Use this to set the plugin path if needed

docs/config/lua/wezterm.plugin/require.md

@@ -0,0 +1,18 @@
+# Function require
+
+{{since('20230320-124340-559cb7b0')}}
+
+Will clone the plugin repo if it doesn't already
+exist and store it in the runtime dir under `plugins/NAME` where
+`NAME` is derived from the repo URL. Once cloned, the repo is
+NOT automatically updated when `require` is called again.
+
+The function takes a single string parameter, the Git repo URL
+
+Only HTTP(S) or local filesystem repos are allowed for the git URL.
+
+```lua
+local remote_plugin = wezterm.plugin.require 'https://github.com/owner/repo'
+local local_plugin =
+  wezterm.plugin.require 'file:///Users/developer/projects/my.Plugin'
+```

docs/config/lua/wezterm.plugin/update_all.md

@@ -0,0 +1,12 @@
+# update_all function
+
+{{since('20230320-124340-559cb7b0')}}
+
+Attempt to fast-forward or `pull --rebase` each of the repos in the plugin directory.
+
+!!! Note
+
+    The configuration is **not** reloaded afterwards; the user will need to do that themselves.
+
+<!-- #TODO How can a user reload the config? -->
+