# HG changeset patch
# User Franz Glasner <hg@dom66.de>
# Date 1522878583 -7200
# Node ID b34ad08e71982452c8d0ed9966baf063192b01e9
# Parent  b11af3ded7c164b62dce6797fb132c442c7f831a
Document the JSON files

diff -r b11af3ded7c1 -r b34ad08e7198 doc/introduction.rst
--- a/doc/introduction.rst	Wed Apr 04 23:36:26 2018 +0200
+++ b/doc/introduction.rst	Wed Apr 04 23:49:43 2018 +0200
@@ -8,7 +8,7 @@
 The configurations can be read from different types of files:
 
 - :ref:`YAML files <yaml-files>`
-- :ref:`JSON files <json-files>`  
+- :ref:`JSON files <json-files>`
 - :ref:`INI files <ini-files>`
 - :ref:`executable Python scripts <executable-python-scripts>`
 
@@ -34,7 +34,21 @@
 JSON files
 ----------
 
-.. todo:: Document basic JSON usage
+Read the JSON file with the help of Python's native :mod:`json` package.
+
+.. note:: All strings are returned as Unicode text strings.
+
+.. note:: The root object must be an *object* and therefore decode into
+          a Python :class:`dict` alike.
+
+.. todo:: Handle JSON comments by special attributes which will
+          filtered out on further processing. Javascript comments are
+          not allowed by the JSON specification.
+
+An example is:
+
+.. literalinclude:: ../tests/data/conf10.json
+   :language: js
 
 
 .. _ini-files: