From f6ad53555ce46de30c991aefe850cc1b389eabe8 Mon Sep 17 00:00:00 2001
From: s3lph <account-gitlab-ideynizv@kernelpanic.lol>
Date: Sat, 30 Nov 2019 04:39:33 +0100
Subject: [PATCH] Add plugin API reference

---
 README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 130 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 959f740..14593f4 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,7 @@ the space as open depending on its existence.
     @plugins.template_function
     def space_state():
         # Get the plugin config dict
-        conf = config.get_plugin_config(filestate')
+        conf = config.get_plugin_config('filestate')
         # Get the filename
         filename = conf.get('filename', '/var/space_state')
         try:
@@ -185,6 +185,135 @@ curl http://localhost:8000/
 
 You should be greeted with the SpaceAPI endpoint response.
 
+## Plugin API Reference
+
+### Configuration
+
+The following functions provide access to values defined in the
+configuration file.
+
+#### `spaceapi_server.config.get_plugin_config(name: str)`
+
+This function returns a plugin's configuration.
+
+The function takes one argument, the name of the plugin.  This name is
+used to look up the plugin configuration.
+
+The function returns the content present at the key `.plugins.<name>`
+of the global configuration file, or an empty object if absent.
+
+Usage:
+
+```python
+from spaceapi_server import config
+
+print(config.get_plugin_config('my_plugin'))
+```
+
+### Templating
+
+The following decorators register a function in the Jinja2
+environment, so they become usable from within templates.  They are
+invoked when the template is rendered, which happens for each HTTP
+request.
+
+If performance is an issue, consider applying caching, either in your
+plugins, or by using a caching HTTP reverse proxy.
+
+#### `spaceapi_server.plugins.template_function`
+
+This decorator registers a function as a **global function** in the
+Jinja2 environment.
+
+The decorated function may take any arguments that can be represented
+in a Jinja2 template.
+
+The decorated function may return any value that can be serialized
+into JSON.  This includes objects and arrays.
+
+Usage:
+
+```python
+from spaceapi_server import plugins
+
+@plugins.template_function
+def lookup_sensor(query, default=None):
+    # Do something with the query
+    result = ...
+    # If the loo
+    if not result:
+        return default or []
+```
+
+```json
+{
+  # ...
+  "state": "{{ lookup_sensor('SELECT timestamp, value FROM people_now_present LIMIT 1') }}"
+  # ...
+}
+```
+
+#### `spaceapi_server.plugins.template_filter`
+
+This decorator registers a function as a **filter** in the Jinja2
+environment.  The decorated function must take at least one argument.
+
+The decorated function may take any arguments that can be represented
+in a Jinja2 template.
+
+The decorated function may return any value that can be serialized
+into JSON.  This includes objects and arrays.
+
+Usage:
+
+```python
+from spaceapi_server import plugins
+
+@plugins.template_filter
+def lookup_sensor(query, default=None):
+    # Do something with the query
+    result = ...
+    # If the loo
+    if not result:
+        return default or []
+```
+
+```json
+{
+  # ...
+  "state": "{{ 'SELECT timestamp, value FROM people_now_present LIMIT 1' | lookup_sensor }}"
+  # ...
+}
+```
+
+#### `spaceapi_server.plugins.template_test`
+
+This decorator registers a function as a **test** in the Jinja2
+environment.  The decorated function must take exactly one argument.
+
+The decorated function may take any argument that can be represented
+in a Jinja2 template.
+
+The decorated function must return either `True` or `False`.
+
+Usage:
+
+```python
+from spaceapi_server import plugins
+
+@plugins.template_test
+def easteregg(expr):
+    return expr == 23
+```
+
+```json
+{
+  # ...
+  message": "{% if people_present() is easteregg -%} Nobody expects the Spanish Iniqusition! {%- endif %}"
+  # ...
+}
+```
+
 [master]: https://gitlab.com/s3lph/spaceapi-server/commits/master
 [releases]: https://gitlab.com/s3lph/spaceapi-server/-/releases
 [spaceapi]: https://spaceapi.io/