Updated sphinx documentation

6 files changed, 240 insertions, 9 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 3750003..6445d97 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,15 +1,14 @@
 API
 ===
 
-.. module:: qface.generator
+.. toctree::
+   :maxdepth: 2
+
+   api_generator
+   api_domain
+
 
-Generator module
-----------------
 
-.. autoclass:: Generator
-   :members:
 
-.. autoclass:: FileSystem
-   :members:
 
 
diff --git a/docs/api_domain.rst b/docs/api_domain.rst
new file mode 100644
index 0000000..6457809
--- /dev/null
+++ b/docs/api_domain.rst
@@ -0,0 +1,5 @@
+Domain module
+=============
+
+.. automodule:: qface.idl.domain
+   :members:
diff --git a/docs/api_generator.rst b/docs/api_generator.rst
new file mode 100644
index 0000000..54ba0b1
--- /dev/null
+++ b/docs/api_generator.rst
@@ -0,0 +1,5 @@
+Generator module
+================
+
+.. automodule:: qface.generator
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
index 18daedd..3436365 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -39,6 +39,9 @@ extensions = [
     'sphinx.ext.githubpages',
 ]
 
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'
+
 sys.path.append(os.path.abspath('..'))
 # sys.path.append(os.path.abspath('.'))
 
@@ -130,7 +133,7 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/docs/idl_grammar.rst b/docs/idl_grammar.rst
index b6e66b1..d0464a1 100644
--- a/docs/idl_grammar.rst
+++ b/docs/idl_grammar.rst
@@ -1,2 +1,103 @@
-IDL grammar
+QDL grammar
 ===========
+
+QDL (Qt definnition language) is an IDL to define an interface. In general it is modelled to define an interface between Qt QML and C++. The QDL syntax is flexible enough to also be used in other context.
+
+.. code-block:: html
+
+    module <module> <version>;
+    import <module> <version>;
+
+    interface <Identifier> {
+        <type> <identifier>;
+        <type> <operation>(<parameter>*);
+        event <type> <event>(<parameter>*);
+    }
+
+    struct <Identifier> {
+        <type> <identifier>;
+    }
+
+    enum <Identifier> {
+        <name> = <value>,
+    }
+
+    flag <Identifier> {
+        <name> = <value>,
+    }
+
+The grammar is seen as a system of modules. 
+
+A module is identified name. A module should be normally a URI where all parts are lowercase (e.g. `entertainment.tuner`). A module can import other modules. This is used to ensure that dependencies are declared inside the QDL file. 
+
+Types are either local and can be references simply by its name, or they are from external module in this case they need to be referenced with the fully qualified name (`module + '.' + name`). A type can be an interface, struct, enum or flag.
+
+A module consist of either one or more interfaces, structs and enums/flags. They can come in any number or combination. The interface is the only type which can contain operations and events. The struct is merely a container to transport structured data. An enum/flag allows the user to encode information used inside the struct or interface as datatype.
+
+The QDL does not allow to extend interfaces. It is by design kept simple.
+
+Below is an example of a QDL file.
+
+.. code-block:: thrift
+
+    module entertainment.tuner 1.0;
+
+    import common 1.0
+
+    /*! Service Tuner */
+    interface Tuner {
+        /*! property currentStation */
+        readonly Station currentStation;
+        /*! operation nextStation */
+        void nextStation();
+        /*! operation previousStation */
+        void previousStation();
+        /*! operation updateCurrentStation */
+        void updateCurrentStation(int stationId);   
+
+        list<int> primitiveList;
+        list<Station> complexList;
+        model<int> primitiveModel;
+        model<Station> complexModel;
+    }
+
+    /*! enum State */
+    enum State {
+        /*! value State.Null */
+        Null=0,
+        /*! value State.Loading */
+        Loading=1,
+        /*! value State.Ready */
+        Ready=2,
+        /*! value State.Error */
+        Error=3
+    }
+
+    /*! enum Waveband */
+    enum Waveband {
+        /*! value Waveband.FM */
+        FM=0,
+        /*! value Waveband.AM */
+        AM=1
+    }
+
+    flag Features {
+        Mono = 0x1,
+        Stereo = 0x2,
+    }
+
+    /*! struct Station */
+    struct Station {
+        /*! member stationId */
+        int stationId;
+        /*! member name */
+        string name;
+        /*! last time modified */
+        common.TimeStamp modified;
+    } 
+
+
+
+
+
+
diff --git a/docs/usage.rst b/docs/usage.rst
index d4b9a15..2350b5e 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,2 +1,120 @@
 Usage
 =====
+
+QFace requires one or more IDL files as input file and a generator to produce output files. The IDL files are named QDL (Qt definition language).
+
+There is a central client to interface the commands for generation, called cli.
+
+To use an existing generator just provide the path to the generator script.
+
+.. code-block:: sh
+
+    ./cli.py generator --generator generator/csv --input input --output output
+
+You can also create a YAML configuration file (e.g csv.yaml):
+
+.. code-block:: yaml
+
+    generator: generator/csv
+    input: input
+    output: output
+
+And then call the client with:
+
+.. code-block:: sh
+
+    ./cli.py generate --runner csv.yaml
+
+To enable auto-live reloading just use the monitor target:
+
+
+.. code-block:: sh
+
+    ./cli.py generator_monitor --runner csv.yaml
+
+This will observe the generator folder and the input folder for changes and re-run the generator.
+
+Grammar
+=======
+
+The IDL grammar is described in the grammar file (see qface/parser/idl/T.g4)
+
+.. code-block:: html
+
+    module <identifier> <version>;
+
+    [import <identifier> <version>];
+
+    interface <identifier> {
+        (readonly) <type> <property>;
+        <type> <operation>([type name]);
+        event <type> <operation>([type name]);
+        list<type> <property>;
+        model<type> <property>;
+    }
+
+    enum <identifier> {
+        <name> = <value>
+    }
+
+    flag <identifier> {
+        <name> = <value>
+    }
+
+    struct <identifier> {
+        <type> <name>;
+    }
+
+
+Domain Model
+============
+
+The IDL is converted into an in memory domain model (see qface/idl/domain.py).
+
+.. code-block:: yaml
+
+    - System
+        - Module
+            - Import
+            - Service
+                - Property
+                - Operation
+                - Event
+            - Enum
+            - Flag
+            - Struct
+
+The domain model is the base for the code generation.
+
+Code Generation
+===============
+
+The code generation is driven by a small script which iterates over the domain model and writes files using a template language (see http://jinja.pocoo.org) and espcially the template designer documentation (http://jinja.pocoo.org/docs/dev/templates/).
+
+.. code-block:: python
+
+    from qface.generator import FileSystem, Generator
+
+    def generate(input, output):
+        system = FileSystem.parse_dir(input)
+        generator = Generator(searchpath='templates')
+        ctx = {'output': output, 'system': system}
+        generator.write('{{output}}/modules.csv', 'modules.csv', ctx)
+
+This script reads the input directory returns a system object form the domain model. This is used as the root object for the code generation inside the template language.
+
+.. code-block:: jinja
+
+    {% for module in system.modules %}
+        {%- for interface in module.interfaces -%}
+        SERVICE, {{module}}.{{interface}}
+        {% endfor -%}
+        {%- for struct in module.structs -%}
+        STRUCT , {{module}}.{{struct}}
+        {% endfor -%}
+        {%- for enum in module.enums -%}
+        ENUM   , {{module}}.{{enum}}
+        {% endfor -%}
+    {% endfor %}
+
+The template iterates over the domain objects and generates text which is written into a file. The file name is also adjustable using the same template language.