summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarcelo Lira <marcelo.lira@openbossa.org>2011-01-12 11:17:58 -0300
committerMarcelo Lira <marcelo.lira@openbossa.org>2011-01-25 08:32:20 -0300
commit13480bf7867bed1cfa64613fddb0d6e53aa36b9e (patch)
tree970e5b96df3652a899a4a6552b0dd00603a3cd65
parenta2318f763a91bc7c47bb751e39036ab95f4b45fc (diff)
Added documentation for command line and XML generator project file options.
-rw-r--r--doc/commandlineoptions.rst76
-rw-r--r--doc/contents.rst2
-rw-r--r--doc/overview.rst2
-rw-r--r--doc/projectfile.rst71
4 files changed, 150 insertions, 1 deletions
diff --git a/doc/commandlineoptions.rst b/doc/commandlineoptions.rst
new file mode 100644
index 00000000..0761982d
--- /dev/null
+++ b/doc/commandlineoptions.rst
@@ -0,0 +1,76 @@
+.. _command-line:
+
+Command line options
+********************
+
+Usage
+-----
+
+::
+
+ generator [options] header-file typesystem-file
+
+
+Options
+-------
+
+.. _api-version:
+
+``--api-version``
+ Specify the supported api version used to generate the bindings.
+
+.. _debug-level:
+
+``--debug-level=[sparse|medium|full]``
+ Set the debug level.
+
+.. _documentation-only:
+
+``--documentation-only``
+ Do not generate any code, just the documentation.
+
+.. _generation-set:
+
+``--generation-set``
+ Generator set to be used (e.g. qtdoc).
+
+.. _help:
+
+``--help``
+ Display this help and exit.
+
+.. _include-paths:
+
+``--include-paths=<path>[:<path>:...]``
+ Include paths used by the C++ parser.
+
+.. _license-file=[license-file]:
+
+``--license-file=[license-file]``
+ File used for copyright headers of generated files.
+
+.. _no-suppress-warnings:
+
+``--no-suppress-warnings``
+ Show all warnings.
+
+.. _output-directory:
+
+``--output-directory=[dir]``
+ The directory where the generated files will be written.
+
+.. _silent:
+
+``--silent``
+ Avoid printing any message.
+
+.. _typesystem-paths:
+
+``--typesystem-paths=<path>[:<path>:...]``
+ Paths used when searching for type system files.
+
+.. _version:
+
+``--version``
+ Output version information and exit.
+
diff --git a/doc/contents.rst b/doc/contents.rst
index 5abd13bc..c21930a7 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -5,3 +5,5 @@ Table of contents
:maxdepth: 3
overview.rst
+ commandlineoptions.rst
+ projectfile.rst
diff --git a/doc/overview.rst b/doc/overview.rst
index 6191c0ed..5f50610f 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -4,7 +4,7 @@
Generator Overview
******************
-In a few words, the Generator is a utility that parses a collecion of header and
+In a few words, the Generator is a utility that parses a collection of header and
typesystem files, generating other files (code, documentation, etc.) as result.
Creating new bindings
diff --git a/doc/projectfile.rst b/doc/projectfile.rst
new file mode 100644
index 00000000..6b91bc9d
--- /dev/null
+++ b/doc/projectfile.rst
@@ -0,0 +1,71 @@
+.. _project-file:
+
+********************
+Binding Project File
+********************
+
+Instead of directing the Generator behaviour via command line, the binding developer
+can write a XML project file describing the same information, and avoid the hassle
+of a long stream of command line arguments.
+
+.. _project-file-structure:
+
+The project file structure
+==========================
+
+Here follows a comprehensive example of a generator project file.
+
+ .. code-block:: xml
+
+ <?xml version="1.0"?>
+ <generator-project>
+ <generator-set generator="path/to/generator/CHOICE_GENERATOR" />
+ <header-file location="DIR/global.h" />
+ <typesystem-file location="DIR/typesystem_for_your_binding.xml" />
+ <output-directory location="OUTPUTDIR" />
+ <include-paths>
+ <path location="path/to/library/being/wrapped/headers/1" />
+ <path location="path/to/library/being/wrapped/headers/2" />
+ </include-paths>
+ <typesystem-paths>
+ <path location="path/to/directory/containing/type/system/files/1" />
+ <path location="path/to/directory/containing/type/system/files/2" />
+ </typesystem-paths>
+ <enable-parent-ctor-heuristic />
+ </generator-project>
+
+
+Project file tags
+=================
+
+The generator project file tags are in direct relation to the
+:ref:`command line arguments <command-line>`. All of the current command line
+options provided by |project| were already seen on the :ref:`<project-file-structure>`,
+for new command line options provided by additional generator modules (e.g.: qtdoc,
+Shiboken) could also be used in the generator project file following simple conversion rules.
+
+For tags without options, just write as an empty tag without any attributes. Example:
+
+ .. code-block:: bash
+
+ --BOOLEAN-ARGUMENT
+
+becomes
+
+ .. code-block:: xml
+
+ <BOOLEAN-ARGUMENT />
+
+and
+
+ .. code-block:: bash
+
+ --VALUE-ARGUMENT=VALUE
+
+becomes
+
+ .. code-block:: xml
+
+ <VALUE-ARGUMENT value="VALUE" />
+
+