diff options
author | Hugo Lima <hugo.lima@openbossa.org> | 2009-08-17 17:32:08 -0300 |
---|---|---|
committer | Hugo Lima <hugo.lima@openbossa.org> | 2009-08-17 17:32:08 -0300 |
commit | 9732e0c744e45a67094fc6ce08bdadb1f9a08d4a (patch) | |
tree | 566e389f406515b040317bffa075f4e5021020f7 /doc |
The genesis...
Diffstat (limited to 'doc')
22 files changed, 2201 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..0f70dfc08 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,88 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf _build/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html + @echo + @echo "Build finished. The HTML pages are in _build/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + @echo + @echo "Build finished. The HTML pages are in _build/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in _build/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in _build/qthelp, like this:" + @echo "# qcollectiongenerator _build/qthelp/APIExtractor.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile _build/qthelp/APIExtractor.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo + @echo "Build finished; the LaTeX files are in _build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + @echo + @echo "The overview file is in _build/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in _build/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in _build/doctest/output.txt." diff --git a/doc/_static/.gitignore b/doc/_static/.gitignore new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/doc/_static/.gitignore diff --git a/doc/_static/basic.css b/doc/_static/basic.css new file mode 100644 index 000000000..2509c227f --- /dev/null +++ b/doc/_static/basic.css @@ -0,0 +1,417 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 0px; + list-style: none; +} + +div.related li { + float: left; + display: inline; + padding-right:17px; + padding-left:10px; + background-image:url(images/bread_crumb.png); + background-position:right; + background-repeat:no-repeat; +} + +div.related li.right { + float: right; + margin-right: 5px; + padding: 0 0 0 0px; + background-image:none; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + text-align: left; + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + text-align: left; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 2px 8px 2px 8px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} diff --git a/doc/_static/default.css b/doc/_static/default.css new file mode 100644 index 000000000..721ceb71b --- /dev/null +++ b/doc/_static/default.css @@ -0,0 +1,248 @@ +/** + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #000000; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-image:url(images/side_background.jpg); + background-repeat:repeat-y; + background-color:#ffd800; +} + +div.body { + position:relative; + background-color:#fff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-image:url(images/top_background.jpg); + background-repeat:repeat-x; + background-color: #d7aa00; + line-height:33px; + height:33px; + color: #000000; +} + +div.related a { + color: #000000; +} + +div.related img { + padding-top:3px; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: Arial, Verdana, sans-serif; + color: #000000; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #000000; +} + +div.sphinxsidebar h4 { + font-family: Arial, Verdana, sans-serif; + color: #000000; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div#searchbox p.searchtip { + color:#000000; + font-size:90%; + padding-top:50px; +} + +div#searchbox { + background-image:url(images/background_search.jpg); + background-repeat:no-repeat; + background-position:center; + border:none; +} + +div.sphinxsidebar a { + color: #009491; +} + + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #009491; + text-decoration: underline; +} + +a:hover { + text-decoration: underline; +} + +div.body p, div.body dd, div.body li { + text-align: left; + line-height: 130%; +} + +div.body h1 { + font-family: Arial, Verdana, sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: Arial, Verdana, Helvetica, sans-serif; + font-size:12px; + font-weight:normal; + border-left-width: 1px; + border-right-width: 1px; + border-top-width: 1px; + border-bottom-width: 2px; + border-style: solid; + border-left-color: #b1b1b1; + border-right-color: #b1b1b1; + border-top-color: #b1b1b1; + border-bottom-color: #009491; + background-color: #e0e0e0; + padding-left:5px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 120%; } +div.body h3 { font-size: 115%; } +div.body h4 { font-size: 110%; } +div.body h5 { font-size: 105%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: left; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +input[type=text]{ + background-color: #009491; + font: 11px verdana, arial, helvetica, sans-serif; + color:#FFFFFF; + width: 150px; + height: 18px; + border: 1px solid #009491; + margin-left:13px; + margin-top:15px; + margin-bottom:4px; + border:none; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} diff --git a/doc/_static/images/._background_search.jpg b/doc/_static/images/._background_search.jpg Binary files differnew file mode 100755 index 000000000..d5c689c31 --- /dev/null +++ b/doc/_static/images/._background_search.jpg diff --git a/doc/_static/images/._bread_crumb.png b/doc/_static/images/._bread_crumb.png Binary files differnew file mode 100755 index 000000000..46b8591c6 --- /dev/null +++ b/doc/_static/images/._bread_crumb.png diff --git a/doc/_static/images/._button_search.jpg b/doc/_static/images/._button_search.jpg Binary files differnew file mode 100755 index 000000000..d5c689c31 --- /dev/null +++ b/doc/_static/images/._button_search.jpg diff --git a/doc/_static/images/._side_background.jpg b/doc/_static/images/._side_background.jpg Binary files differnew file mode 100755 index 000000000..a79b91c97 --- /dev/null +++ b/doc/_static/images/._side_background.jpg diff --git a/doc/_static/images/._top_background.jpg b/doc/_static/images/._top_background.jpg Binary files differnew file mode 100755 index 000000000..d5c689c31 --- /dev/null +++ b/doc/_static/images/._top_background.jpg diff --git a/doc/_static/images/background_search.jpg b/doc/_static/images/background_search.jpg Binary files differnew file mode 100644 index 000000000..c0481c561 --- /dev/null +++ b/doc/_static/images/background_search.jpg diff --git a/doc/_static/images/bg.jpg b/doc/_static/images/bg.jpg Binary files differnew file mode 100644 index 000000000..2ceb19583 --- /dev/null +++ b/doc/_static/images/bg.jpg diff --git a/doc/_static/images/bread_crumb.png b/doc/_static/images/bread_crumb.png Binary files differnew file mode 100644 index 000000000..f7ebd20e4 --- /dev/null +++ b/doc/_static/images/bread_crumb.png diff --git a/doc/_static/images/button_search.png b/doc/_static/images/button_search.png Binary files differnew file mode 100644 index 000000000..0160b81ab --- /dev/null +++ b/doc/_static/images/button_search.png diff --git a/doc/_static/images/side_background.jpg b/doc/_static/images/side_background.jpg Binary files differnew file mode 100644 index 000000000..6e6667542 --- /dev/null +++ b/doc/_static/images/side_background.jpg diff --git a/doc/_static/images/top_background.jpg b/doc/_static/images/top_background.jpg Binary files differnew file mode 100644 index 000000000..aafe1f72e --- /dev/null +++ b/doc/_static/images/top_background.jpg diff --git a/doc/_templates/index.html b/doc/_templates/index.html new file mode 100644 index 000000000..00a829ccc --- /dev/null +++ b/doc/_templates/index.html @@ -0,0 +1,26 @@ +{% extends "layout.html" %} +{% set title = 'Overview' %} +{% block body %} + <h1>API Extractor {{ version }}</h1> + + <p>API Extractor is a tool that eases the development of bindings of Qt-based libraries for high + level languages by automating most of the process. + + <p>API Extractor is based on the + <a href="http://labs.trolltech.com/page/Projects/QtScript/Generator">QtScriptGenerator</a> project.</p> + + <h2>Documentation</h2> + <table class="contentstable" align="center" style="margin-left: 30px"><tr> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("overview") }}">Overview</a><br/> + <span class="linkdescr">how API Extractor works</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typesystem") }}">Typesystem reference</a><br/> + <span class="linkdescr">reference for all typesystem tags</span></p> + </td> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> + <span class="linkdescr">for a complete overview</span></p> + </td></tr> + </table> + +{% endblock %} diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html new file mode 100644 index 000000000..12fed4d0f --- /dev/null +++ b/doc/_templates/layout.html @@ -0,0 +1,34 @@ +{% extends "!layout.html" %} +{% block rootrellink %} + <!--<li><img src="{{ pathto('_static/py.png', 1) }}" alt="" + style="vertical-align: middle; margin-top: -1px"/></li>--> + <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li> +{% endblock %} +{% set reldelim1 = '' %} +{% block extrahead %} + <!--<link rel="shortcut icon" type="image/png" href="{{ pathto('_static/py.png', 1) }}" />--> +{{ super() }} +{% endblock %} + +{% block sidebarsearch %} + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <div style="width:195px;"> + <div style="float:left;"> + <input type="text" name="q" size="18" /> + </div> + <div style="float:right; padding-top:14px; "> + <input type="image" src="{{ pathto('_static/images/button_search.png', 1) }}"/> + </div> + </div> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> +{% endblock %} + diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..77a4122cd --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,195 @@ +# -*- coding: utf-8 -*- +# +# ApiExtractor documentation build configuration file, created by +# sphinx-quickstart on Wed Apr 22 15:04:20 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.refcounting', 'sphinx.ext.coverage'] + +rst_epilog = """ +.. |project| replace:: API Extractor +""" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +#master_doc = 'contents' + +# General information about the project. +project = u'API Extractor' +copyright = u'2009, Nokia Corporation' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.2' +# The full version, including alpha/beta/rc tags. +release = '0.2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# 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 +# documentation. +#html_theme_options = { +#} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = { '' : ''} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +html_additional_pages = { 'index' : 'index.html'} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +html_use_index = True + +# If true, the index is split into individual pages for each letter. +html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'apiextractor.tex', u'API Extractor Documentation', + u'Nokia Corporation', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/doc/contents.rst b/doc/contents.rst new file mode 100644 index 000000000..88362d38d --- /dev/null +++ b/doc/contents.rst @@ -0,0 +1,8 @@ +Table of contents +***************** +.. toctree:: + :numbered: + :maxdepth: 3 + + overview.rst + typesystem.rst diff --git a/doc/dependency-apiextractor.svg b/doc/dependency-apiextractor.svg new file mode 100644 index 000000000..6bec8b5a8 --- /dev/null +++ b/doc/dependency-apiextractor.svg @@ -0,0 +1,360 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="750" + height="230" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="dependency-apiextractor.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="/tmp/dependency-pyside.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3270" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.8,0,0,0.8,10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible"> + <path + id="path3679" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.6315754" + inkscape:cx="375" + inkscape:cy="115" + inkscape:document-units="px" + inkscape:current-layer="svg2" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1278" + inkscape:window-height="949" + inkscape:window-x="1330" + inkscape:window-y="25"> + <sodipodi:guide + orientation="1,0" + position="384.28571,590" + id="guide2601" /> + <sodipodi:guide + orientation="1,0" + position="678.57143,491.42857" + id="guide2603" /> + <sodipodi:guide + orientation="1,0" + position="78.571429,257.14286" + id="guide2605" /> + <sodipodi:guide + orientation="1,0" + position="93.571429,280.71429" + id="guide7565" /> + <sodipodi:guide + orientation="1,0" + position="148.57143,216.42857" + id="guide7567" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-250.44576,-308.53365)" /> + <g + id="g2664" + transform="translate(-162.03535,-115.53321)"> + <path + inkscape:connector-type="polyline" + id="path2869" + d="M 439.27375,270.21407 L 594.99083,193.03351" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <g + transform="translate(166.24286,-190.07976)" + id="g2606"> + <rect + style="fill:#e3e2db;stroke:#000000;stroke-opacity:1" + id="rect7541" + width="211.42857" + height="124.28571" + x="6.6142678" + y="308.16089" + ry="17.142857" /> + <text + xml:space="preserve" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="76.614265" + y="339.74512" + id="text7543"><tspan + sodipodi:role="line" + id="tspan7545" + x="76.614265" + y="339.74512">Boost</tspan></text> + <text + xml:space="preserve" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="76.614265" + y="372.67505" + id="text7547"><tspan + sodipodi:role="line" + id="tspan7549" + x="76.614265" + y="372.67505">Qt Software</tspan></text> + <text + xml:space="preserve" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="76.614265" + y="408.38055" + id="text7551"><tspan + sodipodi:role="line" + id="tspan7553" + x="76.614265" + y="408.38055">INdT/Nokia</tspan></text> + <rect + style="fill:#aaeeff;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" + id="rect7555" + width="43.163269" + height="22.5" + x="21.614267" + y="321.55374" + ry="6.4285707" /> + <rect + style="fill:#b3ff80;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" + id="rect7561" + width="43.163269" + height="22.5" + x="21.614267" + y="355.4823" + ry="6.4285707" /> + <rect + style="fill:#e9ddaf;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" + id="rect7563" + width="43.163269" + height="22.5" + x="21.614267" + y="390.4823" + ry="6.4285707" /> + </g> + <path + inkscape:connector-type="polyline" + id="path2604" + d="M 782.79015,270.0418 L 627.07307,192.86124" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <g + transform="translate(234.84929,-73.143707)" + id="g5193"> + <rect + ry="9.2689295" + style="fill:#b3ff80;fill-rule:evenodd;stroke:#2a7800;stroke-width:0.96558368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="rect2417" + width="274.18781" + height="73.282379" + x="78.571426" + y="342.86383" + rx="8.3239012" /> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="88.822823" + y="359.67014" + id="text2419"><tspan + sodipodi:role="line" + id="tspan2421" + x="88.822823" + y="359.67014">Qt 4.5</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="88.822823" + y="375.33484" + id="text2423"><tspan + sodipodi:role="line" + id="tspan2425" + x="88.822823" + y="375.33484">4.5</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="88.822823" + y="390.87479" + id="text2427"><tspan + sodipodi:role="line" + id="tspan2429" + x="88.822823" + y="390.87479">headers and libraries - compile-time and run-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="88.822823" + y="400.84058" + id="text2431"><tspan + sodipodi:role="line" + id="tspan2433" + x="88.822823" + y="400.84058">GNU General Public License v3 /</tspan><tspan + id="tspan2472" + sodipodi:role="line" + x="88.822823" + y="411.1687">GNU Lesser General Public Licence v2.1</tspan></text> + </g> + <g + transform="translate(101.41581,-378.37135)" + id="g5120"> + <rect + rx="10.404889" + ry="13.104635" + style="fill:#e9ddaf;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="rect2441" + width="274.54263" + height="73.281754" + x="384.28571" + y="496.43558" /> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="513.59869" + id="text2443"><tspan + sodipodi:role="line" + id="tspan2445" + x="389.17969" + y="513.59869">libapiextractor</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="529.26337" + id="text2447"><tspan + sodipodi:role="line" + id="tspan2449" + x="389.17969" + y="529.26337">0.2</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="544.80334" + id="text2451"><tspan + sodipodi:role="line" + x="389.17969" + y="544.80334" + id="tspan2453">headers and libraries - compile-time and run-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="560.12628" + id="text2455"><tspan + sodipodi:role="line" + id="tspan2457" + x="389.17969" + y="560.12628">LGPL version 2.1</tspan></text> + </g> + <g + transform="translate(242.40213,-378.858)" + id="g5182"> + <rect + ry="11.287985" + style="fill:#aaeeff;fill-rule:evenodd;stroke:#006078;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="rect2563" + width="274.54263" + height="73.281754" + x="384.28571" + y="648.57843" + rx="10.404877" /> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="665.74158" + id="text2565"><tspan + sodipodi:role="line" + id="tspan2567" + x="389.17969" + y="665.74158">boost::graph</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="681.40625" + id="text2569"><tspan + sodipodi:role="line" + id="tspan2571" + x="389.17969" + y="681.40625">1.38.0</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="696.94623" + id="text2573"><tspan + sodipodi:role="line" + x="389.17969" + y="696.94623" + id="tspan2575">headers and libraries - compile-time and run-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="389.17969" + y="712.26917" + id="text2577"><tspan + sodipodi:role="line" + id="tspan2579" + x="389.17969" + y="712.26917">Boost Software License 1.0</tspan></text> + </g> + </g> +</svg> diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 000000000..471e2439b --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,15 @@ +.. _gen-overview: + +********************** +API Extractor Overview +********************** + +The **API Extractor** library is used by the binding generator to parse headers +of a given library and merge this data with information provided by +typesystem (XML) files, resulting in a representation of how the API should be +exported to the chosen target language. The generation of source code for the +bindings is performed by specific generators using the API Extractor library. + +The API Extractor is based on QtScriptGenerator_ codebase. + +.. _QtScriptGenerator: http://labs.trolltech.com/page/Projects/QtScript/Generator diff --git a/doc/typesystem.rst b/doc/typesystem.rst new file mode 100644 index 000000000..19c46aeb1 --- /dev/null +++ b/doc/typesystem.rst @@ -0,0 +1,810 @@ +The API Extractor Type System +***************************** + +The typesystem is used by a binding generator to map a C++ library API onto +a higher level language. + +The typesystem specification is a handwritten XML document listing the types +that will be available in the generated target language API; types that are not +declared in the specification will be ignored along with everything depending on +them. In addition, it is possible to manipulate and modify types and functions. +It is even possible to use the typesystem specification to inject arbitrary +code into the source files, such as an extra member function. + +The typesystem specification is passed as an argument to the generator. + +Below there is a complete reference guide to the various nodes of the typesystem. +For usage examples, take a look at the typesystem files used to generate the Qt +Python bindings. These files can be found in the data directory of the PySide +package. + +.. _specifying-types: + +Specifying Types +---------------- + +typesystem +^^^^^^^^^^ + + This is the root node containing all the type system information. It can + have a number of attributes, described below. + + .. code-block:: xml + + <typesystem package="..." default-superclass="..."> + </typesystem> + + The **package** attribute is a string describing the package to be used, + e.g. "QtCore". + The *optional* **default-superclass** attribute is the canonical C++ base class + name of all objects, e.g., "object". + +load-typesystem +^^^^^^^^^^^^^^^ + + The load-typesystem node specifies which type systems to load when mapping + multiple libraries to another language or basing one library on another, and + it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <load-typesystem name="..." generate="yes | no" /> + </typesystem> + + The **name** attribute is the filename of the typesystem to load, the + **generate** attribute specifies whether code should be generated or not. The + later must be specified when basing one library on another, making the generator + able to understand inheritance hierarchies, primitive mapping, parameter types + in functions, etc. + + Most libraries will be based on both the QtCore and QtGui modules, in which + case code generation for these libraries will be disabled. + + +rejection +^^^^^^^^^ + + The rejection node rejects the given class, or the specified function or + field, and it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <rejection class="..." + function-name="..." + field-name="..." /> + </typesystem> + + The **class** attribute is the C++ class name of the class to reject. Use the + *optional* **function-name** or **field-name** attributes to reject a particular + function or field. Note that the **field-name** and **function-name** cannot + be specified at the same time. To remove all occurrences of a given field or + function, set the class attribute to \*. You can use an empty class field + to denote a global function. + + +primitive-type +^^^^^^^^^^^^^^ + + The primitive-type node describes how a primitive type is mapped from C++ to + the target language, and is a child of the typesystem node. Note that most + primitives are already specified in the QtCore typesystem. + + .. code-block:: xml + + <typesystem> + <primitive-type name="..." + target-name="..." + preferred-conversion="yes | no" /> + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optimal + **target-name** attribute is the name of the primitive type in the target + language. If the later two attributes are not specified their default value + will be the same as the **name** attribute. + + If the *optional* **preferred-conversion** attribute is set to *no*, it + indicates that this version of the primitive type is not the preferred C++ + equivalent of the target language type. For example, in Python both "qint64" + and "long long" become "long" but we should prefer the "qint64" version. For + this reason we mark "long long" with preferred-conversion="no". + +namespace-type +^^^^^^^^^^^^^^ + + The namespace-type node maps the given C++ namespace to the target language, + and it is a child of the typesystem node. Note that within namespaces, the + generator only supports enums (i.e., no functions or classes). + + .. code-block:: xml + + <typesystem> + <namespace-type name="..." + package="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". The **package** + attribute can be used to override the package of the type system. + +enum-type +^^^^^^^^^ + + The enum-type node maps the given enum from C++ to the target language, + and it is a child of the typesystem node. Use the reject-enum-value to + reject values. + + .. code-block:: xml + + <typesystem> + <enum-type name="..." + flags="yes | no" + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" /> + </typesystem> + + The **name** attribute is the fully qualified C++ name of the enum + (e.g.,"Qt::FillRule"). If the *optional* **flags** attribute is set to *yes* + (the default is *no*), the generator will expect an existing QFlags<T> for the + given enum type. The **lower-bound** and **upper-bound** attributes are used + to specify runtime bounds checking for the enum value. The value must be a + compilable target language statement, such as "QGradient.Spread.PadSpread" + (taking again Python as an example). If the **force-integer** attribute is + set to *yes* (the default is *no*), the generated target language code will + use the target language integers instead of enums. And finally, the + **extensible** attribute specifies whether the given enum can be extended + with user values (the default is *no*). + + +value-type +^^^^^^^^^^ + + The value-type node indicates that the given C++ type is mapped onto the target + language as a value type. This means that it is an object passed by value on C++, + i.e. it is stored in the function call stack. It is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <value-type name="..." + copyable="yes | no" + hash-function="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name, such as + "QMatrix" or "QPainterPath::Element". The **copyable** attribute is used to + force or not specify if this type is copyable. The *optional* **hash-function** + attribute informs the function name of a hash function for the type. + + +object-type +^^^^^^^^^^^ + + The object-type node indicates that the given C++ type is mapped onto the target + language as an object type. This means that it is an object passed by pointer on + C++ and it is stored on the heap. It is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + copyable="yes | no" + hash-function="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. If there is no + C++ base class, the default-superclass attribute can be used to specify a + superclass for the given type, in the generated target language API. The + **copyable** and **hash-function** attributes are the same as described for + :ref:`value-type`. + + +interface-type +^^^^^^^^^^^^^^ + + The interface-type node indicates that the given class is replaced by an + interface pattern when mapping from C++ to the target language. Using the + interface-type node implicitly makes the given type an object type. + + .. code-block:: xml + + <typesystem> + <interface-type name="..." + package ="..." + default-superclass ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The *optional* + **package** attribute can be used to override the package of the type system. + If there is no C++ base class, the *optional* **default-superclass** attribute + can be used to specify a superclass in the generated target language API, for + the given class. + +suppress-warning +^^^^^^^^^^^^^^^^ + + The generator will generate several warnings which may be irrelevant to the + user. The suppress-warning node suppresses the specified warning, and it is + a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <suppress-warning text="..." /> + </typesystem> + + The **text* attribute is the warning text to suppress, and may contain the * + wildcard (use "" to escape regular expression matching if the warning contain + a regular "*"). + + +template +^^^^^^^^ + + The template node registers a template that can be used to avoid duplicate + code when extending the generated code, and it is a child of the typesystem + node. + + .. code-block:: xml + + <typesystem> + <template name="my_template"> + // the code + </template> + </typesystem> + + Use the insert-template node to insert the template code (identified by the + template's **name** attribute) into the generated code base. + + + +.. _value-type-requirements: + +Value Type Requirements +------------------------ + +custom-constructor +^^^^^^^^^^^^^^^^^^ + + In some target languages, such as Python, value types are required to have a + copy constructor. If a C++ class without a copy constructor is mapped onto + the target language as a value type, it is possible to provide a custom + constructor using the custom-constructor node which is a child of the + value-type node. + + .. code-block:: xml + + <value-type> + <custom-constructor + name="..." + param-name="..."> + // code for custom constructor + </custom-constructor> + </value-type> + + The custom constructor's signature becomes: + + T \*name(T \*param-name); + + If not specified the **name** of the constructor becomes + <lowercase type name>_create() and the **param-name** becomes copy. + + **name** and **param-name** attributes are *optional*. + +custom-destructor +^^^^^^^^^^^^^^^^^ + + When a custom constructor is provided using the custom-constructor node, it is + most likely required to clean up the allocated memory. For that reason, it is + also possible to provide a custom destructor using the custom-destructor node + which is a child of the value-type node. + + .. code-block:: xml + + <value-type> + <custom-destructor + name="..." + param-name="..."> + // code for custom destructor + </custom-destructor> + </value-type> + + The custom destructor must have the following signature: + + T \*name(T \*param-name); + + If not specified the **name** of the destructor becomes + <lowercase type name>_delete() and the **param-name** becomes copy. + + **name** and **param-name** attributes are *optional*. + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + + +.. _manipulating-object-and-value-types: + +Manipulating Object and Value Types +----------------------------------- + +inject-code +^^^^^^^^^^^ + The inject-code node inserts the given code into the generated code for the + given type or function, and it is a child of the object-type, value-type and + modify-function nodes. + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end"> + // the code + </inject-code> + </value-type> + + The **class** attribute specifies which module of the generated code that + will be affected by the code injection. The **class** attribute accepts the + following values: + + * native: The c++ code + * target: The binding code + * target-declaration: The code will be injected into the generated header + file containing the c++ wrapper class definition. + + If the **position** attribute is set to *beginning* (the default), the code + is inserted at the beginning of the function. If it is set to *end*, the code + is inserted at the end of the function. + +modify-field +^^^^^^^^^^^^ + + The modify-field node allows you to alter the access privileges for a given + C++ field when mapping it onto the target language, and it is a child of an + object-type or a value-type node. + + .. code-block:: xml + + <object-type> + <modify-field name="..." + write="true | false" + read="true | false" /> + </object-type> + + The **name** attribute is the name of the field, the *optional* **write** + and **read** attributes specify the field's access privileges in the target + language API (both are set to true by default). + +modify-function +^^^^^^^^^^^^^^^ + + The modify-function node allows you to modify a given C++ function when mapping + it onto the target language, and it is a child of an object-type or a value-type + node. Use the modify-argument node to specify which argument the modification + affects. + + .. code-block:: xml + + <object-type> + <modify-function signature="..." + remove="all | c++" + access="public | private | protected" + rename="..." > + </object-type> + + The **signature** attribute is a normalized C++ signature, excluding return + values but including potential const declarations. + + The **remove**, **access** and **rename** attributes are *optional* attributes + for added convenience; they serve the same purpose as the tags remove, access + and rename. + + +include +^^^^^^^ + + Documented in the :ref:`manipulating-namespace-and-interface-types` + + +extra-includes +^^^^^^^^^^^^^^ + + Documented in the :ref:`manipulating-namespace-and-interface-types` + + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + +.. _manipulating-namespace-and-interface-types: + +Manipulating Namespace and Interface Types +------------------------------------------ + +extra-includes +^^^^^^^^^^^^^^ + + The extra-includes node contains declarations of additional include files, + and it can be a child of the interface-type, namespace-type, value-type and + object-type nodes. + + The generator automatically tries to read the global header for each type but + sometimes it is required to include extra files in the generated C++ code to + make sure that the code compiles. These files must be listed using include + nodes witin the extra-include node: + + .. code-block:: xml + + <value-type> + <extra-includes> + <include file-name="..." location="global | local"/> + </extra-includes> + </value-type> + + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". + + +include +^^^^^^^ + + The include node specifies the name and location of a file that must be + included, and it is a child of the interface-type, namespace-type, value-type, + object-type or extra-includes nodes + + The generator automatically tries to read the global header for each type. Use + the include node to override this behavior, providing an alternative file. The + include node can also be used to specify extra include files. + + .. code-block:: xml + + <value-type> + <include file-name="..." + location="global | local"/> + </value-type> + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". + + +.. _manipulating-enum-types: + +Manipulating Enum Types +----------------------- + +reject-enum-value +^^^^^^^^^^^^^^^^^ + + The reject-enum-value node rejects the enum value specified by the **name** + attribute, and it is a child of the enum-type node. + + .. code-block:: xml + + <enum-type> + <reject-enum-value name="..."/> + </enum-type> + + This node is used when a C++ enum implementation has several identical numeric + values, some of which are typically obsolete. + + **WARNING:** If the enum has some duplicated value don't forget to remove one + of them. + + +.. _modifying-functions: + +Modifying Functions +------------------- + +modify-argument +^^^^^^^^^^^^^^^ + + The modify-argument node specifies which of the given function's arguments the + modification affects, and is a child of the modify-function node. Use the + remove-argument, replace-default-expression, remove-default-expression, + replace-type, reference-count and define-ownership nodes to specify the details + of the modification. + + .. code-block:: xml + + <modify-function> + <modify-argument index="return | this | 1 ..." > + // modifications + </modify-argument> + </modify-function> + + Set the **index** attribute to "1" for the first argument, "2" for the second + one and so on. Alternatively, set it to "return" or "this" if you want to + modify the function's return value or the object the function is called upon, + respectively. + + +remove +^^^^^^ + + The remove node removes the given method from the generated target language + API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <remove class="all" /> + </modify-function> + + +access +^^^^^^ + + The access node changes the access privileges of the given function in the + generated target language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <access modifier="public | protected | private"/> + </modify-function> + + +rename +^^^^^^ + + The rename node changes the name of the given function in the generated target + language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <rename to="..." /> + </modify-function> + + The **to** attribute is the new name of the function. + + +inject-code +^^^^^^^^^^^ + + Documented in the :ref:`manipulating-object-and-value-types` + + +argument-map +^^^^^^^^^^^^ + + The argument-map node maps a C++ argument name to the argument name used in + the generated target language API, and is a child of the inject-code node + when the later is a child of a modify-function node. + + .. code-block:: xml + + <modify-function> + <inject-code> + <argument-map index="numeric value" + meta-name="string value"> + </inject-code> + </modify-function> + + The **index** attribute is an index, starting at 1, indicating the argument + position to which this argument mapping applies. The **meta-name** attribute + is the name used within the code injection to adress the argument at the + given position. + + +.. _modifying-arguments: + +Modifying Arguments +------------------- + +remove-argument +^^^^^^^^^^^^^^^ + + The remove-argument node removes the given argument from the function's + signature, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument> + <remove-argument /> + </modify-argument> + + Typically, when removing an argument, some conversion rules must be specified, + e.g., when converting from the target language to C++. This can be done using + the :ref:`conversion-rule` node. + + +remove-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^ + + The remove-default-expression node disables the use of the default expression + for the given argument, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument...> + <remove-default-expression /> + </modify-argument> + +replace-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The replace-default-expression node replaces the specified argument with the + expression specified by the **with** attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-default-expression with="..." /> + </modify-argument> + + +replace-type +^^^^^^^^^^^^ + + The replace-type node replaces the type of the given argument to the one + specified by the **modified-type** attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-type modified-type="..." /> + </modify-argument> + + If the new type is a class, the **modified-type** attribute must be set to + the fully qualified name (including name of the package as well as the class + name). + + Typically when changing the type of an argument some conversion rules must be + specified. This can be done using the :ref:`conversion-rule` node. + + +define-ownership +^^^^^^^^^^^^^^^^ + + The define-ownership tag indicates that the function changes the ownership + rules of the argument object. The **class** attribute specifies the class of + function where to inject the ownership altering code. The **owner** attribute + specifies the new ownership of the object. It accepts the following values: + + * target: the target language will assume full ownership of the object. + The native resources will be deleted when the target language + object is finalized. + * c++: The native code assumes full ownership of the object. The target + language object will not be garbage collected. + * default: The object will get default ownership, depending on how it + was created. + + .. code-block:: xml + + <modify-argument> + <define-ownership class="target | shell" + owner="target | c++ | default" /> + </modify-argument> + + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + +replace-value +^^^^^^^^^^^^^ + + The **replace-value** attribute lets you replace the return statement of a + function with a fixed string. This attribute can only be used for the + argument at **index** 0, which is always the function's return value. + + .. code-block:: xml + + <modify-argument index="0" replace-value="this"/> + + +parent +^^^^^^ + + The **parent** attribute lets you define argument parent which will + take ownership of argument and will destroy the C++ child object when the + parent is destroyed. + + .. code-block:: xml + + <modify-argument> + <parent index="this" action="add | remove" /> + </modify-argument> + + In the **index** argument you must specify the parent argument. The action + *add* creates a parent link between objects, while *remove* will undo the + parentage relationship. + + +.. _using-code-templates: + +Using Code Templates +-------------------- + +insert-template +^^^^^^^^^^^^^^^ + + The insert-template node includes the code template identified by the name + attribute, and it can be a child of the inject-code, conversion-rule, template, + custom-constructor and custom-destructor nodes. + + .. code-block:: xml + + <inject-code class="target" position="beginning"> + <insert-template name="my_template" /> + </inject-code> + + Use the replace node to modify the template code. + + +replace +^^^^^^^ + + The replace node allows you to modify template code before inserting it into + the generated code, and it can be a child of the insert-template node. + + .. code-block:: xml + + <insert-template name="my_template"> + <replace from="..." to="..." /> + </insert-template> + + This node will replace the attribute **from** with the value pointed by + **to**. + + +Manipulating Documentation +-------------------------- + +inject-documentation +^^^^^^^^^^^^^^^^^^^^ + + The inject-documentation node inserts the documentation into the generated + documentation. This node is a child of the object-type, value-type and + modify-function nodes. + + .. code-block:: xml + + <value-type> + <inject-documentation mode="append | prepend | replace" format="native | target" > + // the documentation + </inject-code> + </value-type> + + The **mode** attribute default value is *replace*. + + The **format** attribute specifies when the documentation injection will + occur and it accepts the following values: + + * native: Before XML<->Backend transformation occur, so the injected code *must* be a valid XML. + * target: Before XML<->Backend transformation occur, so the injected code *must* be a valid backend format. + + At the moment the only supported backend is Sphinx. + +modify-documentation +^^^^^^^^^^^^^^^^^^^^ + + The modify-documentation node allows you to change the auto-generated + documentation. API Extractor transforms XML's from qdoc3 (the Qt documentation + tool) into .rst files to be processed later using Sphinx. So you can modify + the XML before the transformation occur. + + .. code-block:: xml + + <modify-documentation xpath="..."> + <!-- new documentation --> + </modify-documentation> + + The **xpath** attribute is the XPath to the node that you want to modify. |