Add more scripting documentation:

  * Added scripting overview section
  * Script types and defining them
  * Added docs for el.Parameter in DSPUI's
  * Added lua examples to sphinx
  * Make examples and built-ins conform to
     documentation

docs/conf.py

@@ -33,7 +33,15 @@
 # ones.
 extensions = [
     'myst_parser',
-    'sphinx_rtd_theme'
+    'sphinx_rtd_theme',
+    'sphinxcontrib.luadomain',
+    'sphinx_lua'
+]
+
+# a list of lua source root
+lua_source_path = [ 
+    "../libs/element/lua/el",
+    "../src/engine" 
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/examples/sysex.lua

@@ -58,7 +58,8 @@ local function process (a, m, p)
     buf:swap (output)
 end
 
-return script.dsp {
+return {
+    type        = 'DSP',
     layout      = layout,
     parameters  = parameters,
     process     = process

docs/examples/sysexui.lua

@@ -57,6 +57,7 @@ local function create_editor (ctx)
     return object.new (Editor, ctx)
 end
 
-return script.dspui {
-    editor = create_editor
+return {
+    type    = 'DSPUI',
+    editor  = create_editor
 }

docs/index.rst

@@ -35,6 +35,9 @@ Welcome to the Element user/developer manual.
    :maxdepth: 1
    :caption: Scripting
 
+   Overview <scripting/overview>
+   scripting/script-types
+   Examples <scripting/examples>
    Element API <https://api.kushview.net/lua/el/latest>
    KV API <https://api.kushview.net/lua/kv/latest>
 

docs/requirements.txt

@@ -1,2 +1,4 @@
 sphinx_rtd_theme
 myst-parser
+sphinxcontrib-luadomain==1.1.2
+sphinx-lua==1.1.3

docs/scripting/examples.rst

@@ -0,0 +1,30 @@
+Example Scripts
+===============
+
+Hello World
+-----------
+.. literalinclude:: ../examples/helloworld.lua
+    :caption: helloworld.lua
+    :name: helloworld-lua
+    :language: lua
+
+Amplifier
+---------
+.. literalinclude:: ../../scripts/amp.lua
+    :caption: amp.lua
+    :name: amp-lua
+    :language: lua
+
+Amplifier UI
+------------
+.. literalinclude:: ../../scripts/ampui.lua
+    :caption: ampui.lua
+    :name: ampui-lua
+    :language: lua
+
+Send MIDI SysEx
+---------------
+.. literalinclude:: ../examples/sysex.lua
+    :caption: sysex.lua
+    :name: sysex-lua
+    :language: lua

docs/scripting/overview.rst

@@ -0,0 +1,42 @@
+Scripting Overview
+==================
+
+Scripts in Element are written in `Lua <https://www.lua.org>`_.
+
+Defining a Script
+-----------------
+
+Scripts must include an `ldoc` style header that define basic metadata about 
+it. The header should include a title, description and a list of properties 
+encapsulated in a Lua comment section.
+
+**Title**
+    This should be the first line of the script.
+
+**Description**
+    Free form text after the first line.
+
+**Properties**
+    =========== ======================================
+    Key         Description
+    =========== ======================================
+    @script     The script's identifier. **required**
+    @kind       The type of script. **required if not 
+                an Anonymous script**
+    @author     Who wrote it
+    @license    License information
+    =========== ======================================    
+
+**Example**
+    .. code-block:: lua
+
+        --- Script Title.
+        --
+        -- The script's description.
+        --
+        -- @script      com.example.script
+        -- @kind        DSP
+        -- @license     GPL v3
+        -- @author      Example Author
+    
+        ...

docs/scripting/script-types.rst

@@ -0,0 +1,167 @@
+.. _kv.AudioBuffer: https://api.kushview.net/lua/kv/latest/classes/kv.AudioBuffer.html
+.. _kv.Widget: https://api.kushview.net/lua/kv/latest/classes/kv.Widget.html
+.. _el.MidiPipe: https://api.kushview.net/lua/el/latest/classes/el.MidiPipe.html
+.. _el.Parameter: https://api.kushview.net/lua/el/latest/classes/el.Parameter.html
+
+Script Types
+============
+Element can execute a range of Lua script types to customize application behavior.
+
+Anonymous
+---------
+This type of script's behavior is determined by the script author.
+
+:kind: N/A
+
+**Arguments:**
+
+    Defined by the script
+
+**Return value:**
+
+    Defined by the script
+
+DSP
+---
+This is a script which executes in a Script Node.  It's purpose is to create custom
+audio and MIDI processing in your Session.
+
+:kind: DSP
+
+**Arguments:**
+
+    None
+
+**Return value:**
+
+    Descriptor table in the following form:
+
+.. lua:attribute:: type: string
+
+    The type of script. MUST equal ``DSP`` for this kind of script.
+
+.. lua:function:: layout()
+
+    Specify the number of audio and midi inputs and outputs. Return a table
+    with keys specifying the data type (audio or midi) and values defining
+    the channel counts (pair of integers)
+
+    :return: Table specifying input and output channels.
+    :rtype: table
+
+    .. code-block:: lua
+        
+        -- A 1 MIDI in and 2 Audio out DSP script
+        local function my_layout()
+            return {
+                audio = { 0, 2 },
+                midi  = { 1, 0 }
+            }
+        end
+
+.. lua:function:: parameters()
+    
+    Specify the parameters. Return a list of tables with key/value pairs 
+    defining the params.
+
+    ===========     ================================
+    **name**        (string) The parameter name
+    **label**       (string) Value label. e.g. dB
+    **min**         (number) Minimum value
+    **max**         (number) Maximum value
+    **default**     (number) Default value
+    ===========     ================================
+
+    :return: The parameters.
+    :rtype: table
+
+.. lua:function:: prepare (rate, block)
+    
+    Prepare for rendering. Allocate needed resources here.
+
+    :param rate: Sample rate
+    :type rate: number
+    :param block: Block size
+    :type block: integer
+
+.. lua:function:: process (audio, midi, params)
+
+    Process audio and MIDI. The passed in buffers require replace processing.
+
+    :param audio: The audio buffer to use
+    :type audio: `kv.AudioBuffer`_
+    :param midi: The midi to use
+    :type midi: `el.MidiPipe`_
+    :param params: Array of parameter values
+    :type params: array
+
+.. lua:function:: release()
+
+    Release allocated resources.
+
+.. lua:function:: save()
+
+    Save the current state. This is an optional function you can implement to save state.  
+    The host will prepare the IO stream so all you have to do is 
+    ``io.write(...)`` your data.
+
+    Note: Parameter values will automatically be saved and restored,
+    you do not need to handle them here.
+
+    .. code-block:: lua
+
+        local function my_save()
+            io.write ("some custom state data")
+        end
+
+.. lua:function:: restore()
+
+    Restore state. This is an optional function you can implement to restore state.  
+    The host will prepare the IO stream so all you have to do is 
+    ``io.read(...)`` your data previsouly written in ``save()``
+
+    .. code-block:: lua
+
+        function my_restore()
+            print ("restored data:")
+            print (io.read ("*a"));
+        end
+
+DSPUI
+-----
+This is a UI for a DSP script.
+
+:kind: DSPUI
+
+**Arguments:**
+
+    None
+
+**Return value:**
+
+    A descriptor table in the following form:
+
+.. lua:attribute:: type: string
+
+    Must always equal ``DSPUI``
+
+.. lua:function:: editor(ctx)
+
+    Implement this and return a kv.Widget to be used as the editor for the DSP 
+    script. The editor UI will be displayed in the Plugin Window of the Script Node.
+
+    Note: DSPUI scripts must be able to create multiple instances of it's widgets. Do
+    not create singleton widgets and return them in this method.
+
+    The ``ctx`` parameter is a table with the following keys.
+
+    ==========  ==========================================
+    **params**  (array) List of `el.Parameter`_ objects as 
+                defined in the DSP script.
+    ==========  ==========================================
+
+    :param ctx: The owner context of this
+    :type ctx: table
+
+    :return: The widget to use as the editor.
+    :rtype: `kv.Widget`_

libs/element/lua/el/Parameter.cpp

@@ -0,0 +1,30 @@
+/// A Parameter.
+// A variable property of a Node. 
+// @classmod el.Parameter
+// @pragma nostrip
+
+/// Handlers.
+// @section handlers
+
+/// Value changed handler.
+// Implement this to handle when the value changes. If you call Parameter:set
+// from inside this callback, be careful to not create an infinte callback loop.
+// @function Parameter:valuechanged
+// @within Handlers
+// @usage
+// -- The first argument, `self`, will be the Parameter object
+// param.valuechanged = function (self)
+//     local value = self:get()
+//     print (value)
+// end
+
+/// Methods.
+// @section methods
+
+/// Get the current value.
+// @function Parameter:get
+// @treturn number The currrent value
+
+/// Set the current value.
+// @function Parameter:set
+// @number value The new value to set

libs/element/lua/el/command.lua

@@ -58,8 +58,8 @@ function M.closure (cmd, async)
     return function() return M.invoke (c, a) end
 end
 
--- Define standard commands as constants. e.g. Commands::showAbout in C++ 
--- becomes command.SHOW_ABOUT
+-- Define standard commands as constants. 
+-- e.g. Commands::showAbout in C++ becomes command.SHOW_ABOUT
 for _,cmd in ipairs (CommandManager.standard()) do
     local slug = require ('kv.slug')
     local s = CommandManager.tostring (cmd)

libs/element/lua/el/script.lua

@@ -2,21 +2,6 @@
 -- @module el.script
 local M = {}
 
-local function define (desc, kind)
-    assert (type(desc) == 'table', "Expected table descriptor")
-    desc.type = tostring (kind) or ''
-    return desc
-end
-
---- Define a DSP script.
--- @usage script.dsp {
---     process = process
--- }
-function M.dsp (desc) return define (desc, 'DSP') end
-
---- Define a DSPUI script.
-function M.dspui (desc) return define (desc, 'DSPUI') end
-
 --- Load a known script.
 -- @function load
 -- @string path The script to run
@@ -29,7 +14,7 @@ function M.load (path, env)
     return nil, e
 end
 
---- Run a known script
+--- Run a known script.
 -- @function exec
 -- @string path The script to run
 -- @tparam table env The environment to use or _ENV