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 00000000..991e3cb5
--- /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 8f46422e..880790d4 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