diff options
author | Juergen Bocklage-Ryannel <juergen@ryannel.org> | 2019-02-20 16:14:36 +0100 |
---|---|---|
committer | Juergen Bocklage-Ryannel <juergen@ryannel.org> | 2019-02-20 16:14:36 +0100 |
commit | 7f60e91e3a91a7cb04cfacbc9ce80f43df444853 (patch) | |
tree | 9be0ec80860bc51f6441e9d384bbcde8bb912d6d | |
parent | 6bb0098b901be17d410db44ef3cb8ca87fefc261 (diff) |
update docs for qface v2 usage
-rw-r--r-- | docs/domain.rst | 46 | ||||
-rw-r--r-- | docs/extending.rst | 98 | ||||
-rw-r--r-- | docs/index.rst | 2 | ||||
-rw-r--r-- | docs/usage.rst | 20 |
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. |