--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/dev-plugin/validation-example-plugin.rst	Tue Aug 10 14:29:28 2010 +0300
@@ -0,0 +1,88 @@
+.. _validation-plugin-howto-example-plugin:
+
+Example ConfML validation plug-in
+=================================
+
+The example plug-in implements a simple ConfML validator class, and so demostrates
+how ConfML validation can be extended by plug-ins.
+
+The extra validation in this case is as follows: we have a requirement that if
+a string-type ConfML setting's reference starts with ``FOO_``, its value
+should also contain the string ``foo``. For example, consider the following
+file:
+
+.. code-block :: xml
+    :linenos:
+    
+    <?xml version="1.0" encoding="UTF-8"?>
+    <configuration xmlns="http://www.s60.com/xml/confml/1" name="ExampleValidatorTest">
+        <feature ref="ExampleValidatorTest" name="Settings for example validator testing">
+            <setting ref="SomeSetting" name="Some setting" type="string"/>
+            <setting ref="FOO_SomeSetting1" name="FOO - Some setting 1" type="string"/>
+            <setting ref="FOO_SomeSetting2" name="FOO - Some setting 2" type="string"/>
+        </feature>
+        <data>
+            <ExampleValidatorTest>
+                <SomeSetting>foo bar</SomeSetting>
+                <FOO_SomeSetting1>abc foo</FOO_SomeSetting1>
+                <FOO_SomeSetting2>abc123</FOO_SomeSetting2>
+            </ExampleValidatorTest>
+        </data>
+    </configuration>
+
+Here two settings are prefixed with ``FOO_``, but only one of them has ``foo``
+in its value, thus our custom validator should report a warning for the value
+on line 12.
+
+Directory structure
+-------------------
+
+- ``plugins/`` - Root directory for all ConE plug-in sources
+    - ``example/`` - Example plug-in package directory
+        - ``ConeExampleValidatorPlugin/`` - Source for the example validator plug-in
+            - ``examplevalidatorplugin/`` - Module directory containing all plug-in code
+                - ``tests/`` - Unit tests and test data for the plug-in
+                    - ``testdata/`` - Directory containing all test data needed by the test cases
+                    - ``__init__.py`` - Test module initialization file
+                    - ``runtests.py`` - Script for running all test cases
+                    - ``unittest_validation.py`` - File containing test cases
+                - ``__init__.py`` - Plug-in module initialization file
+                - ``validators.py`` - Plug-in source file
+            - ``setup.py`` - Setup script for packaging the plug-in into an .egg file
+            - ``setup.cfg`` - Configuration file for ``setup.py``
+
+Plug-in code
+------------
+
+validators.py
+.............
+
+This file defines the validator class. The validator simply goes through all
+``ConfmlStringSetting`` instances in the configuration and checks their values.
+
+.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/validators.py
+   :linenos:
+
+
+unittest_validation.py
+......................
+
+The tests for the plug-in simply contain one test case that tests the validator
+with the example ConfML file shown earlier, using the ``assert_problem_list_equals_expected()``
+method provided by the ``testautomation`` module.
+
+.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/tests/unittest_validation.py
+   :linenos:
+
+
+Plug-in packaging
+-----------------
+
+The file ``setup.py`` handles the packaging of the plug-in into an egg file.
+
+The most important thing here is the plug-in's entry point info. The list
+of validator classes provided by the plug-in must be specified as an entry
+point. The entry point group in this case is ``cone.plugins.confmlvalidators``.
+
+.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/setup.py
+   :linenos: