# HG changeset patch
# User Franz Glasner <hg@dom66.de>
# Date 1521925784 -3600
# Node ID aa0c61e79660fa1b6ff9fcc23f584d0e01adfbc9
# Parent  5b667c252f8c0f0e85637f42d32b6cc05fcfaeb2
Add a documentation section about basic API usage: loading (and merging)

diff -r 5b667c252f8c -r aa0c61e79660 doc/introduction.rst
--- a/doc/introduction.rst	Sat Mar 24 21:05:31 2018 +0100
+++ b/doc/introduction.rst	Sat Mar 24 22:09:44 2018 +0100
@@ -113,3 +113,39 @@
 
 .. literalinclude:: ../tests/data/conf10.py
    :language: python
+
+
+.. _loading-and-merging:
+
+Loading and Merging
+-------------------
+
+Basic usage of the API is as follows in this example::
+
+    import configmix
+
+    #
+    # Note: With conf10 merging is rather pointless because the tree
+    # files # are really the same configuration. But is doesn't harm
+    # also here.
+    #
+    config = configmix.load("conf10.yml", "conf10.ini", "conf10.py")
+
+    # Get a -- possibly interpolated -- configuration variable's value
+    value1 = config.getvar_s("key1")
+
+    # Get a -- possibly interpolated -- variable from within the tree
+    value2 = config.getvar_s("tree1.tree2.key4")
+
+
+The filenames of the configuration files must have the extensions
+(case-insensitively):
+
+  ``.py``
+    for Python configuration files
+
+  ``.yml`` or ``.yaml``
+    for YAML configuration files
+
+  ``.ini``
+    for INI configuration files