diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/plugins/dev-plugin/example-plugin.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/dev-plugin/example-plugin.rst Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,284 @@
+.. _plugin-howto-example-plugin:
+
+Example plug-in
+===============
+
+The example plug-in implements a simple Implementation Markup Language that can write
+text files with possibly some content coming from ConfML setting values. The plug-in
+demonstrates some recommended practices for developing ConE plug-ins:
+
+- Plug-in structure:
+ - Reader class
+ - Implementation class
+ - Implementation model
+- Using ``cone.public.utils`` for ConfML setting reference handling
+- Unit tests:
+ - Testing the reader class, the implementation class and the model classes separately
+ - Output generation testing (plug-in scope integration test)
+
+The ExampleML language
+----------------------
+
+The Implementation Markup Language in the example plug-in is ExampleML. The language
+offers a simple mechanism to write text files to the output directory. For example:
+
+.. code-block :: xml
+
+
+
+
+
+
+
+To demonstrate the use of ConfML setting references, the language supports also
+those with the form ``${Feature.Setting}``. This is the usual way of using them
+in implementation languages, and it is recommended to use the same convention
+in all ImplMLs. For example:
+
+.. code-block :: xml
+
+
+
+
+
+
+.. _plugin-howto-example-plugin-dir-structure:
+
+Directory structure
+-------------------
+
+- ``plugins/`` - Root directory for all ConE plug-in sources
+ - ``example/`` - Example plug-in package directory
+ - ``ConeExamplePlugin/`` - Source for the example plug-in
+ - ``examplemlplugin/`` - Module directory containing all plug-in code
+ - ``tests/`` - Unit tests and test data for the plug-in
+ - ``project/`` - Configuration project used in the tests
+ - ``gen_expected/`` - Expected output for generation test case
+ - ``__init__.py`` - Test module initialization file
+ - ``runtests.py`` - Script for running all test cases
+ - ``unittest_exampleml_impl.py`` - File containing test cases
+ - ``unittest_exampleml_reader.py`` - File containing test cases
+ - ``unittest_exampleml_generation.py`` - File containing test cases
+ - ``__init__.py`` - Plug-in module initialization file
+ - ``exampleml_impl.py`` - Plug-in source file
+ - ``exampleml_reader.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``
+ - ``integration-test/`` - Integration tests for the example plug-in package
+ - ``testdata/`` - Test data for the integration tests
+ - ``__init__.py`` - Test module initialization file
+ - ``runtests.py`` - Script for running all test cases
+ - ``export_standalone.py`` - Script for exporting extra data for standalone test export
+ - ``unittest_generate.py`` - File containing test cases
+
+Logical structure
+-----------------
+
+Logically the plug-in is divided into three parts:
+
+- *Implementation model*, represents the logical model of the implementation specified in the XML data
+- *Implementation class*, works as the interface of the plug-in towards ConE and uses the model to do the actual work
+- *Implementation reader*, converts the XML data into the logical model and creates a new implementation class instance
+
+In this case the *model* consists just of the class Output, which corresponds to the ``