Commit e567637d authored by George Kiagiadakis's avatar George Kiagiadakis
Browse files

docs: convert lua api docs to pure rst

Not all the docs are there yet, this is WIP
parent c3ee5250
......@@ -18,13 +18,9 @@ extensions = [
breathe_projects = {
"WirePlumber": "@OUTDIR@/wp/xml",
"WirePlumber_Lua" : "@OUTDIR@/lua/xml",
}
breathe_default_project = "WirePlumber"
breathe_default_members = ('members', 'protected-members', 'undoc-members')
primary_domain = 'c'
breathe_domain_by_extension = {
"h" : "c",
"c" : "c",
......@@ -47,3 +43,5 @@ html_static_path = ['@SRCDIR@/_static']
html_css_files = ['custom.css']
graphviz_output_format = "svg"
pygments_style = "friendly"
......@@ -52,28 +52,6 @@ endif
# Build documentation
if build_doc
doxy_lua_input = [
meson.source_root() / 'modules' / 'module-lua-scripting' / 'api.c',
meson.source_root() / 'modules' / 'module-lua-scripting' / 'pod.c',
]
doxy_lua_conf_data = configuration_data()
doxy_lua_conf_data.set('OUTPUT_DIR', meson.current_build_dir() / 'lua')
doxy_lua_conf_data.set('INPUT', ' \\\n '.join(doxy_lua_input))
doxyfile_lua = configure_file(
input: 'Doxyfile.in',
output: 'Doxyfile-lua',
configuration: doxy_lua_conf_data
)
doxyxml_lua_depfiles = doxy_lua_input
doxyxml_lua = custom_target('doxyxml_lua',
command: [doxygen_p, doxyfile_lua],
depend_files: doxyxml_lua_depfiles,
output: 'lua',
build_by_default: true,
)
sphinx_files = files(
'_static'/'custom.css',
meson.source_root()/'README.rst',
......@@ -102,10 +80,9 @@ if build_doc
],
depend_files: [
sphinx_conf, sphinx_files,
doxyfile_wp, doxyfile_lua,
doxyxml_wp_depfiles, doxyxml_lua_depfiles,
doxyfile_wp, doxyxml_wp_depfiles,
],
depends: [doxyxml_wp, doxyxml_lua],
depends: [doxyxml_wp],
output: 'html',
install: true,
install_dir: get_option('datadir') / 'doc' / 'wireplumber',
......
......@@ -7,18 +7,11 @@ Lua API Documentation
:maxdepth: 1
:caption: Contents:
lua_api/lua_gobject.rst
lua_api/lua_core_api.rst
lua_api/lua_client_api.rst
lua_api/lua_endpoint_api.rst
lua_api/lua_global_proxy_api.rst
lua_api/lua_metadata_api.rst
lua_api/lua_node_api.rst
lua_api/lua_object_api.rst
lua_api/lua_object_interest_api.rst
lua_api/lua_object_manager_api.rst
lua_api/lua_pipewire_object_api.rst
lua_api/lua_proxy_api.rst
lua_api/lua_session_bin_api.rst
lua_api/lua_object_interest_api.rst
lua_api/lua_proxies_api.rst
lua_api/lua_session_item_api.rst
lua_api/lua_source_api.rst
lua_api/lua_spa_device_api.rst
.. _lua_client_api:
Lua Client Documentation
------------------------
.. doxygenstruct:: Client
:project: WirePlumber_Lua
:members:
.. _lua_core_api:
Lua Core Documentation
----------------------
.. doxygenstruct:: Core
:project: WirePlumber_Lua
:members:
\ No newline at end of file
Core
====
.. _lua_endpoint_api:
Lua Endpoint Documentation
--------------------------
.. doxygenstruct:: Endpoint
:project: WirePlumber_Lua
:members:
.. _lua_global_proxy_api:
Lua Global Proxy Documentation
------------------------------
.. doxygenstruct:: GlobalProxy
:project: WirePlumber_Lua
:members:
.. _lua_gobject:
GObject Integration
===================
The Lua engine that powers WirePlumber's scripts provides direct integration
with `GObject`_. Most of the objects that you will deal with in the lua scripts
are wrapping GObjects. In order to work with the scripts, you will first need
to have a basic understanding of GObject's basic concepts, such as signals and
properties.
Properties
..........
All GObjects have the ability to have `properties`_.
In C we normally use `g_object_get`_ to retrieve them and `g_object_set`_
to set them.
In WirePlumber's lua engine, these properties are exposed as object members
of the Lua object.
For example:
.. code-block:: lua
-- read the "bound-id" GObject property from the proxy
local proxy = function_that_returns_a_wp_proxy()
local proxy_id = proxy["bound-id"]
print("Bound ID: " .. proxy_id)
Writable properties can also be set in a similar fashion:
.. code-block:: lua
-- set the "scale" GObject property to the enum value "cubic"
local mixer = ...
mixer["scale"] = "cubic"
Signals
.......
GObjects also have a generic mechanism to deliver events to external callbacks.
These events are called `signals`_
All lua objects that wrap a GObject contain the following methods:
.. function:: connect(detailed_signal, callback)
Connects the signal to a callback. When the signal is emitted by the
underlying object, the callback will be executed.
:param detailed_signal: the signal name to listen to
(of the form "signal-name::detail")
:param callback: a lua function that will be called when the signal is emitted
.. function:: call(action_signal, ...)
Calls an action signal on this object.
:param action_signal: the signal name to call
:param ...: a list of arguments that will be passed to the signal
.. _GObject: https://developer.gnome.org/gobject/stable/
.. _properties: https://developer.gnome.org/gobject/stable/gobject-properties.html
.. _g_object_get: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-get
.. _g_object_set: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-set
.. _signals: https://developer.gnome.org/gobject/stable/signal.html
.. _lua_metadata_api:
Lua Metadata Documentation
--------------------------
.. doxygenstruct:: Metadata
:project: WirePlumber_Lua
:members:
.. _lua_node_api:
Lua Node Documentation
----------------------
.. doxygenstruct:: Node
:project: WirePlumber_Lua
:members:
.. _lua_object_api:
Lua Object Documentation
------------------------
.. doxygenstruct:: Object
:project: WirePlumber_Lua
:members:
WpObject
========
.. _lua_object_interest_api:
Lua Object Interest Documentation
---------------------------------
Object Interest
===============
.. doxygenstruct:: ObjectInterest
:project: WirePlumber_Lua
:members:
Constructors
~~~~~~~~~~~~
.. function:: Interest(decl)
:param table decl: an interest declaration
:returns: the interest
:rtype: ObjectInterest
Methods
~~~~~~~
.. function:: Interest.matches(self, obj)
:param self: the interest
:param obj: an object to check for a match
:type obj: GObject or table
:returns: whether the object matches the interest
:rtype: boolean
.. _lua_object_manager_api:
Lua Object Manager Documentation
---------------------------------
Object Manager
==============
.. doxygenstruct:: ObjectManager
:project: WirePlumber_Lua
:members:
Constructors
~~~~~~~~~~~~
.. function:: ObjectManager(interest_list)
Constructs a new object manager.
Combines :c:func:`wp_object_manager_new` and
:c:func:`wp_object_manager_add_interest_full`
:param table interest_list: a list of `interests <lua_object_interest_api>`_
to objects
:returns: a new object manager
:rtype: ObjectManager
Methods
~~~~~~~
.. function:: ObjectManager.activate(self)
Activates the object manager.
Binds :c:func:`wp_core_install_object_manager`.
:param self: the object manager
.. function:: ObjectManager.get_n_objects(self)
Binds :c:func:`wp_object_manager_get_n_objects`
:param self: the object manager
:returns: the number of objects managed by the object manager
:rtype: integer
.. function:: ObjectManager.iterate(self, interest)
Binds :c:func:`wp_object_manager_new_filtered_iterator_full`
:param self: the object manager
:param ObjectInterest interest: an interest to filter objects, or nil
:returns: all the managed objects that match the interest
:rtype: Iterator; the iteration items are of type `GObject <lua_gobject>`_
.. function:: ObjectManager.lookup(self, interest)
Binds :c:func:`wp_object_manager_lookup`
:param self: the object manager
:param ObjectInterest interest: the interest to use for the lookup, or nil
:returns: the first managed object that matches the interest
:rtype: `GObject <lua_gobject>`_
.. _lua_pipewire_object_api:
Lua PipewireObject Documentation
------------------------
.. doxygenstruct:: PipewireObject
:project: WirePlumber_Lua
:members:
.. _lua_proxies_api:
PipeWire Proxies
================
Proxy
.....
Lua objects that bind a :ref:`WpProxy <proxy_api>` contain the following methods:
.. function:: Proxy.get_interface_type(self)
Binds :c:func:`wp_proxy_get_interface_type`
:param self: the proxy
:returns: the proxy type, the proxy type version
:rtype: string, integer
PipeWire Object
...............
Lua objects that bind a :ref:`WpPipewireObject <pipewire_object_api>`
contain the following methods:
.. function:: PipewireObject.iterate_params(self, param_name)
Binds :c:func:`wp_pipewire_object_enum_params_sync`
:param self: the proxy
:param string param_name: the PipeWire param name to enumerate,
ex "Props", "Route"
:returns: the available parameters
:rtype: Iterator; the iteration items are `Spa Pod <lua_spa_pod>`_ objects
.. function:: PipewireObject.set_params(self, param_name, pod)
Binds :c:func:`wp_pipewire_object_set_param`
:param self: the proxy
:param string param_name: The PipeWire param name to set, ex "Props", "Route"
:param Pod pod: A Spa Pod object containing the new params
Global Proxy
............
Lua objects that bind a :ref:`WpGlobalProxy <global_proxy_api>`
contain the following methods:
.. function:: GlobalProxy.request_destroy(self)
Binds :c:func:`wp_global_proxy_request_destroy`
:param self: the proxy
PipeWire Node
.............
Lua objects that bind a :ref:`WpNode <node_api>` contain the following methods:
.. function:: Node.send_command(self, command)
Binds :c:func:`wp_node_send_command`
:param self: the proxy
:param string command: the command to send to the node (ex "Suspend")
PipeWire Client
...............
Lua objects that bind a :ref:`WpClient <client_api>`
contain the following methods:
.. function:: Client.update_permissions(self, perms)
Binds :c:func:`wp_client_update_permissions`
Takes a table where the keys are object identifiers and the values are
permission strings.
Valid object identifiers are:
- A number, meaning the bound ID of a proxy
- The string "any" or the string "all", which sets the default permissions
for this client
The permission strings have a chmod-like syntax (ex. "rwx" or "r-xm"), where:
- "r" means permission to read the object
- "w" means permission to write data to the object
- "x" means permission to call methods on the object
- "m" means permission to set metadata for the object
- "-" is ignored and can be used to make the string more readable when
a permission flag is omitted
**Example:**
.. code-block:: lua
client:update_permissions {
["all"] = "r-x",
[35] = "rwxm",
}
:param self: the proxy
:param table perms: the permissions to update for this client
PipeWire Metadata
.................
Lua objects that bind a :ref:`WpMetadata <metadata_api>`
contain the following methods:
.. function:: Metadata.iterate(self, subject)
Binds :c:func:`wp_metadata_new_iterator`
:param self: the proxy
:param integer subject: the subject id
:returns: an iterator
.. function:: Metadata.find(self, subject, key)
Binds :c:func:`wp_metadata_find`
:param self: the proxy
:param string subject: the subject id
:param string key: the metadata key to find
:returns: the value for this metadata key, the type of the value
:rtype: string, string
.. _lua_proxy_api:
Lua Proxy Documentation
-----------------------
.. doxygenstruct:: Proxy
:project: WirePlumber_Lua
:members:
.. _lua_session_bin_api:
Lua Session Bin Documentation
------------------------------
.. doxygenstruct:: SessionBin
:project: WirePlumber_Lua
:members:
.. _lua_session_item_api:
Lua Session Item Documentation
------------------------------
Session Item
============
.. doxygenstruct:: SessionItem
:project: WirePlumber_Lua
:members:
Lua objects that bind a :ref:`WpSessionItem <session_item_api>`
contain the following methods:
.. function:: SessionItem.get_associated_proxy(self, type)
Binds :c:func:`wp_session_item_get_associated_proxy`
:param self: the session item
:param string type: the proxy type name
:returns: the proxy object or nil
.. function:: SessionItem.reset(self)
Binds :c:func:`wp_session_item_reset`
:param self: the session item
.. function:: SessionItem.configure(self, properties)
Binds :c:func:`wp_session_item_configure`
:param self: the session item
:param table properties: The configuration properties
:returns: true on success, false on failure
:rtype: boolean
.. function:: SessionItem.register(self)
Binds :c:func:`wp_session_item_register`
:param self: the session item
.. function:: SessionItem.remove(self)
Binds :c:func:`wp_session_item_remove`
:param self: the session item
.. _lua_source_api:
Lua Source Documentation
------------------------
.. doxygenstruct:: Source
:project: WirePlumber_Lua
:members:
.. _lua_spa_device_api:
Lua Spa Device Documentation
----------------------------
Spa Device
==========
.. doxygenstruct:: SpaDevice
:project: WirePlumber_Lua
:members:
.. function:: SpaDevice.get_managed_object(self, id)
Binds :c:func:`wp_spa_device_get_managed_object`
:param self: the spa device
:param integer id: the object id
:returns: the managed object or nil
.. function:: SpaDevice.store_managed_object(self, id, object)
Binds :c:func:`wp_spa_device_store_managed_object`
:param self: the spa device
:param integer id: the object id
:param GObject object: a GObject to store or nil to remove the existing
stored object
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment