From 6a5e67b3837070c791f88b63e485e799bb9e900f Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Sat, 7 Jul 2018 11:43:18 +0200
Subject: [PATCH] docs: add documentation for site library
---
docs/dev/site_library.rst | 36 ++++++++++++++++++++++++++++++++++++
docs/index.rst | 1 +
2 files changed, 37 insertions(+)
create mode 100644 docs/dev/site_library.rst
diff --git a/docs/dev/site_library.rst b/docs/dev/site_library.rst
new file mode 100644
index 000000000..991e3cb52
--- /dev/null
+++ b/docs/dev/site_library.rst
@@ -0,0 +1,36 @@
+gluon.site library
+==================
+
+The *gluon.site* library allows convenient access to the site configuration
+from Lua scripts. Example:
+
+.. code-block:: lua
+
+ local site = require 'gluon.site'
+ print(site.wifi24.ap.ssid())
+
+The *site* object in this example does not directly represent the *site.conf* data structure;
+instead, it is wrapped in a way that makes it more convenient to access deeply nested elements.
+To access the the underlying values, they must be unwrapped using the function call notation
+(the ``()`` after ``site.wifi24.ap.ssid`` in the example).
+
+The wrapper objects have two advantages over simple Lua tables:
+
+* Accessing non-existing values is never an error: ``site.wifi24.ap.ssid()`` will simply
+ return *nil* if ``site.wifi24`` or ``site.wifi24.ap`` do not exist
+* Default values: A default value can be passed to the unwrapping function call:
+
+ .. code-block:: lua
+
+ print(site.wifi24.ap.ssid('Default'))
+
+ will return *'Default'* instead of *nil* when the value is unset.
+
+ Note that *nil* values and unset values are equivalent in Lua.
+
+A simple way to access the whole site configuration as a simple table
+is to unwrap the top-level site object:
+
+.. code-block:: lua
+
+ local site_table = site()
diff --git a/docs/index.rst b/docs/index.rst
index 8f46422ed..880790d4d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,6 +40,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
dev/upgrade
dev/wan
dev/mac_addresses
+ dev/site_library
.. toctree::
:caption: gluon-web Reference
--
GitLab