update docs for qface v2 usage

4 files changed, 140 insertions, 26 deletions

diff --git a/docs/domain.rst b/docs/domain.rst
index df27987..464de59 100644
--- a/docs/domain.rst
+++ b/docs/domain.rst
@@ -16,12 +16,11 @@ The IDL is converted into an in memory domain model (see qface/idl/domain.py)
                 - Property
                 - Operation
                 - Signal
+            - Struct
             - Enum
             - Flag
-            - Struct
 
-
-The domain model is the base for the code generation. You traverse the domain tree and trigger your own code generation.
+The domain model is the base for the code generation. You traverse the domain tree and trigger your own code generation. Below you see a python example to traverse the model. Normally you do not need todo this, as the rules generator does the traversing for you.
 
 .. code-block:: python
 
@@ -29,7 +28,7 @@ The domain model is the base for the code generation. You traverse the domain tr
 
     system = FileSystem.parse('./interfaces')
 
-    for module in sytem.modules:
+    for module in system.modules:
         print(module.name)
 
         for interfaces in module.interfaces:
@@ -39,22 +38,23 @@ The domain model is the base for the code generation. You traverse the domain tr
             print(struct.name)
 
 
-Debug
------
-
-At any time you can place a debug breakpoint:
-
-.. code-block:: python
-
-    import ipdb; ipd.set_trace()
-
-
-See https://pypi.python.org/pypi/ipdb
-
-
-To see the object members just use:
-
-.. code-block:: python
-
-    dir(module) # list all members of module
-    help(module) # prints the documentation
+The rules generator calls the template directive for each domain element found and it is up to the template to place the code in the right place.
+
+.. code-block:: yml
+
+    project:
+        system:
+            documents:
+                - '{{system}}.txt': 'system.txt'
+        module:
+            documents:
+                - '{{module}}.txt': 'module.txt'
+        interface:
+            documents:
+                - '{{interface}}.txt': 'interface.txt'
+        struct:
+            documents:
+                - '{{struct}}.txt': 'struct.txt'
+        enum:
+            documents:
+                - '{{enum}}.txt': 'enum.txt'
diff --git a/docs/extending.rst b/docs/extending.rst
index faf4ccb..d968c76 100644
--- a/docs/extending.rst
+++ b/docs/extending.rst
@@ -2,8 +2,102 @@
 Extending
 *********
 
-QFace is easy to use and easy to extend. Your generator is just a small python
-script using the qface library.
+QFace is easy to use and easy to extend with your own generator. The standard way is to write a rules document to control the code generation. The more complicated path is to write your generator using just a small python script which uses qface as library.
+
+Rules Extensions
+================
+
+The rules extension uses a YAML based document to control the code generation. The document is structured roughly like this:
+
+.. code-block:: yml
+
+    <scope>:
+        when: <feature-list>
+        context: <context map update>
+        path: <target path prefix>
+        source: <source prefix>
+        <qualifier>:
+            when: <feature-list>
+            context: <context map update>
+            path: <target path prefix>
+            source: <source prefix>
+            documents:
+                - <target>: <source>
+            preserved:
+                - <target>: <source>
+
+
+.. rubric:: `scope` entry
+
+Scope is a logical distribution of generator. For example if you write a client/server generator you may want to have a ``client`` and ``server`` scope. This enables you also to switch a scope off using the ``when`` condition.
+
+.. rubric:: `qualifier` entry
+
+The qualifier defines the domain model type this code generation section shall be applied to. Valid qualifiers are ``system``, ``module``, ``interface``, ``struct`` and ``enum``.
+
+
+.. rubric:: `when` entry
+
+The  `when` entry defines a condition when this part of the code generation is enabled. For example you may have some code generation parts, which create a scaffold project. By passing in the scaffold flag or by  enabling the scaffold feature this part would then also be evaluated. By default when is true.
+
+.. rubric:: `context` entry
+
+The contexct map allows you to extend the cotnext given to the template. Each context key will then accessible in the template.
+
+.. rubric:: `path` entry
+
+The path is the path appended to the target directory. So the full export path for a template is ``<target>/<path>/<template>``.
+
+.. rubric:: `source` entry
+
+The source prefixed to the template name. For example to not to repeat the ``server`` folder for the next templates you can set the ``source`` to ``server``.
+
+
+.. rubric:: `documents` entry
+
+The documents section is a list of target, source templates. The source defines the template document used to produce the target document. The target document can have a fully qualified template syntax, for example ``{{interface}}.h``, where the interface name is looked up using the given context. When generating existing documents will be overriden.
+
+.. rubric:: `preserve` entry
+
+Very similar to the documents section. The only difference is that existing documents will be preserved. You can overrule this using the ``--force`` command line option.
+
+Preserved is useful when generated document shall be edited by the user and a new run of the generator shall not overwrite (preserve) the edited document.
+
+.. rubric:: Example
+
+Below is a more complex rules document from the qtcpp generator using one scope called ``project``.
+
+.. code-block:: yaml
+
+    project:
+        system:
+            documents:
+                - '{{project}}.pro': 'project.pro'
+                - '.qmake.conf': 'qmake.conf'
+                - 'CMakeLists.txt': 'CMakeLists.txt'
+        module:
+            path: '{{module|identifier}}'
+            documents:
+                - 'CMakeLists.txt': 'plugin/CMakeLists.txt'
+                - 'qmldir': 'plugin/qmldir'
+                - 'generated/generated.pri': 'plugin/generated/generated.pri'
+                - 'generated/{{module|identifier}}_gen.h': 'plugin/generated/module.h'
+                - 'generated/{{module|identifier}}_gen.cpp': 'plugin/generated/module.cpp'
+                - 'docs/plugin.qdocconf': 'plugin/docs/plugin.qdocconf'
+                - 'docs/plugin-project.qdocconf': 'plugin/docs/plugin-project.qdocconf'
+                - 'docs/docs.pri': 'plugin/docs/docs.pri'
+            preserve:
+                - '{{module|identifier}}.pro': 'plugin/plugin.pro'
+                - 'plugin.cpp': 'plugin/plugin.cpp'
+                - 'plugin.h': 'plugin/plugin.h'
+        interface:
+            preserve:
+                - '{{interface|lower}}.h': 'plugin/interface.h'
+                - '{{interface|lower}}.cpp': 'plugin/interface.cpp'
+
+
+Script Extensions
+=================
 
 The script iterates over the domain model and writes files using a template
 language.
diff --git a/docs/index.rst b/docs/index.rst
index e7a6e42..46a35a8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,7 @@
 QFace
 =====
 
-* see https://github.com/pelagicore/qface
+.. note:: Repository is hosted at https://github.com/pelagicore/qface
 
 QFace is a flexible API generator inspired by the Qt API idioms. It uses a common IDL format (called QFace interface document) to define an API. QFace is optimized to write a custom generator based on the common IDL format.
 
diff --git a/docs/usage.rst b/docs/usage.rst
index 4256012..f992995 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -35,8 +35,20 @@ The code generation is driven by a rules document which applies the domain model
 
 .. note:: Refer to http://jinja.pocoo.org and particularly the template designer documentation at http://jinja.pocoo.org/docs/dev/templates/.
 
+The initial folder structure should have a rules file and in the templates folder the required templates.
+
+.. code-block:: text
+
+  qface-rules.yml
+  templates/report.tpl
+
+
+The rules document provides the rules for code-generation.
+
+
 .. code-block:: yaml
 
+    # qface-rules.yml
     project:
         system:
             - project_report.csv: report.tpl
@@ -67,6 +79,14 @@ You call the yaml document by calling the qface executable and provide the rules
 
     qface --rules rules-qface.yaml --target output echo.qface
 
+The output would then look like this.
+
+.. code-block:: text
+
+  output/project_report.csv
+
+
+.. rubric:: More ...
 
 To know more about the different options just ask the help of qface.