diff options
Diffstat (limited to 'sources/shiboken2/ApiExtractor/doc')
29 files changed, 2221 insertions, 0 deletions
diff --git a/sources/shiboken2/ApiExtractor/doc/CMakeLists.txt b/sources/shiboken2/ApiExtractor/doc/CMakeLists.txt new file mode 100644 index 000000000..d78844dc8 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/CMakeLists.txt @@ -0,0 +1,10 @@ + +find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") + +if (SPHINX) + message("-- sphinx-build - found") + configure_file(conf.py.in conf.py @ONLY) + add_custom_target(doc ${SPHINX} -b html -c . ${CMAKE_CURRENT_SOURCE_DIR} html ) +else() + message("-- sphinx-build - not found! doc target disabled") +endif()
\ No newline at end of file diff --git a/sources/shiboken2/ApiExtractor/doc/_templates/index.html b/sources/shiboken2/ApiExtractor/doc/_templates/index.html new file mode 100644 index 000000000..4aa14ede5 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_templates/index.html @@ -0,0 +1,27 @@ +{% extends "layout.html" %} +{% set title = 'Overview' %} +{% block body %} +<div class="section"> + <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"><tr> + <td width="50%"> + <p class="biglink"><a href="{{ pathto("overview") }}">Overview</a><br/> + <span class="linkdescr">how API Extractor works</span></p> + <p class="biglink"><a 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 href="{{ pathto("contents") }}">Contents</a><br/> + <span class="linkdescr">for a complete overview</span></p> + </td></tr> + </table> +</div> +{% endblock %} diff --git a/sources/shiboken2/ApiExtractor/doc/_templates/layout.html b/sources/shiboken2/ApiExtractor/doc/_templates/layout.html new file mode 100644 index 000000000..9dc53722d --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_templates/layout.html @@ -0,0 +1,41 @@ +{% extends "!layout.html" %} + +# Invert sidebars +{%- block sidebar1 %}{{ sidebar() }}{%- endblock %} +{%- block sidebar2 %}{%- endblock %} + +{%- block header %} +<div id="container"> +<div class="header"> + <div class="header_container"> + <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}" width="199" height="102" /></a></div> + <div class="related"> + <ul> + {%- block rootrellink %} + <li><a href="{{ pathto( 'index' ) }}">{{ shorttitle|e }}</a></li> + {%- endblock %} + {%- for parent in parents %} + <li>{{ reldelim1 }} <a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a></li> + {%- endfor %} + {%- block relbaritems %} {% endblock %} + </ul> + </div> + </div> +</div> +{%- endblock -%} + +{%- block footer %} + <div class="footer"> + <a href="http://www.indt.org.br"><img src="{{ pathto('_static/logo_indt.jpg', 1) }}" alt="Indt" border="0" /></a> + <a href="http://www.openbossa.org"><img src="{{ pathto('_static/logo_openbossa.png', 1) }}" alt="Openbossa" border="0" /></a> + <a href="http://qt.nokia.com/"><img src="{{ pathto('_static/logo_qt.png', 1) }}" alt="Qt" border="0" /></a> + <a href="http://www.python.org"><img src="{{ pathto('_static/logo_python.jpg', 1) }}" alt="Python" border="0" /></a> + </div> +</div> +{%- endblock %} + +# No top relbar. +{%- block relbar1 %}{%- endblock %} + +# No bottom relbar. +{%- block relbar2 %}{%- endblock %} diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/searchbox.html b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/searchbox.html new file mode 100644 index 000000000..55a972156 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/searchbox.html @@ -0,0 +1,12 @@ +{%- if pagename != "search" %} +<div id="searchbox" style="display: none"> + <h3>{{ _('Quick search') }}</h3> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" id="q" size="18" /> + <input type="submit" value="{{ _('Go') }}" id="search_button" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> +{%- endif %} diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_header.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_header.png Binary files differnew file mode 100644 index 000000000..843e7e2c5 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_header.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_topo.jpg b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_topo.jpg Binary files differnew file mode 100644 index 000000000..4229ae8db --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/bg_topo.jpg diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/fakebar.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/fakebar.png Binary files differnew file mode 100644 index 000000000..b45830e00 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/fakebar.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_indt.jpg b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_indt.jpg Binary files differnew file mode 100644 index 000000000..2a1fbe7a1 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_indt.jpg diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_openbossa.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_openbossa.png Binary files differnew file mode 100644 index 000000000..51e868d6e --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_openbossa.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_python.jpg b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_python.jpg Binary files differnew file mode 100644 index 000000000..cd474efba --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_python.jpg diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_qt.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_qt.png Binary files differnew file mode 100644 index 000000000..37800f454 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/logo_qt.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidedocs.css b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidedocs.css new file mode 100644 index 000000000..fd81f4379 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidedocs.css @@ -0,0 +1,409 @@ +* { + font: 100% Verdana, Arial, Helvetica, sans-serif; + font-size:12px; +} + +html { + height: 100%; +} + +body { + margin: 0; + padding: 0; + text-align: center; + background-color: #EBEBEB; + height: 100%; + color: #333; +} + +strong { + font-weight:bold; +} + +.document { + padding-bottom: 90px; +} + +#container { + position: relative; + min-height: 100%; + background-image: url(fakebar.png); + background-repeat: repeat-y; + background-color: white; +} + +.footer { + position: absolute; + bottom: 0px; + margin-top: 50px; + text-align:center; + background-color: white; + border-top: 2px solid #e0e0e0; + white-space: nowrap; + height: 90px; + width: 100%; +} + +.footer img { + margin-left: 8px; + margin-right: 8px; +} + +.sphinxsidebar { + float: left; + width: 250px; + padding: 0px 10px 0px 10px; + text-align: left; +} + +.sphinxsidebar ul { + padding: 0px; + margin: 0px; + list-style-position: inside; +} + +.sphinxsidebar > ul { + padding: 0px; + margin: 0px; +} + +.sphinxsidebar ul li { + margin-left: 10px; + padding: 0px; +} + +.sphinxsidebar h3, .sphinxsidebar h3 a { + font-weight: bold; + color: #333; +} + +.documentwrapper { + margin-left: 270px; + text-align: left; + background-color: #ffffff; + border-left: 1px solid #989898; + font-size:18px; + padding: 10px 50px 15px 50px; + height: 100%; +} + +h1 { + font-size:18px; + padding-left: 50px; + padding-bottom: 15px; + padding-top: 15px; + border-bottom: 1px solid #c2c2c2; + text-transform:uppercase; + margin-right: -100px; + position: relative; + left: -50px; + top: -10px; +} + +h2 { + font-size:12px; + font-weight:bold; + 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:5px; + margin-top: 20px; + -moz-border-radius:5px; + -webkit-border-radius:5px; + -khtml-border-radius:5px; +} + +h3, h4 { + font-weight: bolder; +} + +pre { + border-top: 1px solid #e0e0e0; + border-bottom: 1px solid #e0e0e0; + background-color: #fafafa; + padding: 5px; + font: 100% monospace; + overflow: auto; +} + +pre * { + font: 100% monospace; +} + +.headerlink { + font-size: 100%; + color: inherit; + float: right; + visibility: Hidden; +} + +h1 .headerlink { + padding-right: 50px; +} + +h1:hover .headerlink, h2:hover .headerlink, h3:hover .headerlink { + visibility: Visible; +} + +a, a:visited { + color: #009491; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +/* -- 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; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.note { + border: 1px solid #e3e3e3; +} + +table.docutils { + margin-left: auto; + margin-right: auto; + margin-bottom: 10px; + border: none; +} + +table.docutils td { + border: none; +} + +table.docutils th { + border: none; + font-weight: bold; + vertical-align: top; +} + +h2 em { + float: right; + font-size: 10px; + position: relative; + top: -20px; +} + +/* Table of pymaemo components */ + +#development table.docutils td { + border-bottom: 1px solid #EBEBEB; +} + +#development th { + background-color: #EBEBEB; + color: #FC7E00; + padding: 5px; +} + +#development th:first-child { + -moz-border-radius: 20px 0px 0px 0px; + -webkit-border-radius: 20px 0px 0px 0px; + -khtml-border-radius: 20px 0px 0px 0px; + padding-left: 10px; +} +#development th:last-child { + -moz-border-radius: 0px 20px 0px 0px; + -webkit-border-radius: 0px 20px 0px 0px; + -khtml-border-radius: 0px 20px 0px 0px; + padding-right: 10px; + width: 100px; +} + +hr { + border: none; + border-bottom: 1px dashed #EBEBEB; + width: 70% +} + +.oldnews { + text-align: right; +} + +/******************* TOPO *****************************/ +.header { + background-image: url(bg_topo.jpg); + background-repeat: repeat-x; + height: 147px; +} + +.header_container { + background-image: url(bg_header.png); + background-repeat: no-repeat; + background-position: 100px 0px; +} + +.logo { + text-align: left; + margin-bottom: 10px; +} + +#searchbox { + border-top: 1px solid #989898; + padding-top: 10px; + margin-left: -10px; + margin-right: -10px; + padding-left: 10px; + padding-right: 10px; +} + +#search_button { + border: 1px solid #3A393A; + background-color: #3A393A; + color: white; + cursor: pointer; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + +} + +form { + margin: 0px; + padding: 0px; +} + +/* search field */ +form #q { + width: 136px; +/* height: 22px; */ + border: none; + margin: 0px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + margin-top: 2px; + padding: 4px; + line-height: 22px +} + +#search-results h2 { + display: none; +} + +#search-results h2 { + display: none; +} + +#search-results ul.search { + margin: 0px; + padding: 0px; +} + +ul.search div.context { + padding-left: 40px; +} + +#installation td { + text-align: center; + font-weight: bold; +} + +em { + color: inherit; + font-style:italic; +} + +/******** REL bar *********/ + +.related { + display: inline; +} + +.related ul { + padding: 0px 0px 0px 10px; + margin: 0px; + text-align: left; + background-image: url(relbar_bg.png); +} + +.related li { + display: inline; + color: white; + font-weight: bold; +} + +.related li a { + color: inherit; + line-height: 35px; + font-weight: bold; + vertical-align: middle; +} + +.related li.right { + float: right; + margin-right: 5px; +} + +.related h3 { + display: none; +} + +.align-center { + text-align: center; +} + +.contentstable { + width: 100%; +} + +.contentstable td { + padding-left: 30px; + vertical-align: top; +} + +p.biglink a { + font-size: 20px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +img { + border: 0px; +} + +.figure .caption { + font-style:italic; +} + +table.footnote { + margin: 0px; +} diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidelogo.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidelogo.png Binary files differnew file mode 100644 index 000000000..076c1057c --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/pysidelogo.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/relbar_bg.png b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/relbar_bg.png Binary files differnew file mode 100644 index 000000000..4036733a7 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/static/relbar_bg.png diff --git a/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/theme.conf b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/theme.conf new file mode 100644 index 000000000..e0a652a5d --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/_themes/pysidedocs/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = default +stylesheet = pysidedocs.css +pygments_style = none + +[options] +nosidebar = false diff --git a/sources/shiboken2/ApiExtractor/doc/conf.py.in b/sources/shiboken2/ApiExtractor/doc/conf.py.in new file mode 100644 index 000000000..70750c899 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/conf.py.in @@ -0,0 +1,163 @@ +# -*- 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 = ['@CMAKE_CURRENT_SOURCE_DIR@/_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-2010, 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 = '@apiextractor_MAJOR_VERSION@.@apiextractor_MINOR_VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@apiextractor_VERSION@' + +# 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 = 'pysidedocs' + +# 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 = ['@CMAKE_CURRENT_SOURCE_DIR@/_themes'] + +# 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 = ['@CMAKE_CURRENT_SOURCE_DIR@/_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 index is generated. +html_use_index = False + +# 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 = False + +html_add_permalinks = 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 = '' + diff --git a/sources/shiboken2/ApiExtractor/doc/contents.rst b/sources/shiboken2/ApiExtractor/doc/contents.rst new file mode 100644 index 000000000..83a4889fe --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/contents.rst @@ -0,0 +1,9 @@ +Table of contents +***************** +.. toctree:: + :numbered: + :maxdepth: 3 + + overview.rst + ownership.rst + typesystem.rst diff --git a/sources/shiboken2/ApiExtractor/doc/dependency-apiextractor.svg b/sources/shiboken2/ApiExtractor/doc/dependency-apiextractor.svg new file mode 100644 index 000000000..6bec8b5a8 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/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/sources/shiboken2/ApiExtractor/doc/overview.rst b/sources/shiboken2/ApiExtractor/doc/overview.rst new file mode 100644 index 000000000..471e2439b --- /dev/null +++ b/sources/shiboken2/ApiExtractor/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/sources/shiboken2/ApiExtractor/doc/ownership.rst b/sources/shiboken2/ApiExtractor/doc/ownership.rst new file mode 100644 index 000000000..760967da6 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/ownership.rst @@ -0,0 +1,85 @@ +Ownership Management +******************** + +Among the various types of instances interactions, sometimes an object +may be *owned* by another object, so that the owner is responsible for +destroying the owned object, like in Qt's object system [#]_. +This kind of relationship has a big role on interfacing with the target language, like +with Python's reference counting. + + +Ownership transfers +------------------- + +From C++ to target +^^^^^^^^^^^^^^^^^^ + + When an object that is currently owned by C++ has its ownership transfered + back to the target language, the binding can know for sure when the object will be deleted and + tie the C++ instance existence to the wrapper, calling the C++ destructor normally when the + wrapper is deleted. + + .. code-block:: xml + + <modify-argument index="1"> + <define-ownership class="target" owner="target" /> + </modify-argument> + + +From target to C++ +^^^^^^^^^^^^^^^^^^ + + In the opposite direction,when an object ownership is transfered from the target language + to C++, the native code takes full control of the object life and you don't + know when that object will be deleted, rendering the wrapper object invalid, + unless you're wrapping an object with a virtual destructor, + so you can override it and be notified of its destruction. + + By default it's safer to just render the wrapper + object invalid and raise some error if the user tries to access + one of this objects members or pass it as argument to some function, to avoid unpleasant segfaults. + Also you should avoid calling the C++ destructor when deleting the wrapper. + + .. code-block:: xml + + <modify-argument index="1"> + <define-ownership class="target" owner="c++" /> + </modify-argument> + + +Parent-child relationship +------------------------- + +One special type of relationship is the parent-child. When an object is called +the parent of another object (the child), the former is in charge of deleting its +child when deleted and the target language can trust that the child will be alive +as long as the parent is, unless some other method can take the C++ ownership away from the parent. + +One of the main uses of this scheme is Qt's object system, with ownership among QObject-derived +classes, creating "trees" of instances. + + .. code-block:: xml + + <modify-argument index="this"> + <parent index="1" action="add"> + </modify-argument> + +In this example, the instance with the method that is being invoked (indicated by 'index="this"' on +modify-argument) will be marked as a child +of the first argument using the `parent` tag. To remove ownership, just use "remove" in the action attribute. **Removing +parentship also transfers the ownership back to python.** + +Invalidation after use +---------------------- + +Sometimes an object is created as a virtual method call argument and destroyed after the +call returned. In this case, you should use the ``invalidate-after-use`` attribute in the +``modify-argument`` tag to mark the wrapper as invalid right after the virtual method returns. + + .. code-block:: xml + + <modify-argument index="2" invalidate-after-use="yes"/> + +In this example the second argument will be invalidated after this method call. + +.. [#] See *Object Trees and Object Ownership* http://doc.trolltech.com/4.5/objecttrees.html diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem.rst b/sources/shiboken2/ApiExtractor/doc/typesystem.rst new file mode 100644 index 000000000..69dda43a0 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem.rst @@ -0,0 +1,29 @@ +The API Extractor Type System +***************************** + +The typesystem is used by a binding generator or any other software using the APIExtractor library +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. + +Below there is a complete reference guide to the various nodes (XML tags) of the typesystem. +For usage examples, take a look at the typesystem files used to generate PySide. These files +can be found in the PySide/<QT_MODULE_NAME> directory of the PySide package. + +.. toctree:: + + typesystem_specifying_types + typesystem_manipulating_objects + typesystem_modify_function + typesystem_arguments + typesystem_solving_compilation + typesystem_templates + typesystem_conversionrule + typesystem_documentation + + diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst new file mode 100644 index 000000000..16e0678d3 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_arguments.rst @@ -0,0 +1,192 @@ +.. _modifying-arguments: + +Modifying Arguments +------------------- + +.. _conversion-rule: + +conversion-rule +^^^^^^^^^^^^^^^ + + The conversion-rule node allows you to write customized code to convert + the given argument between the target language and C++, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument ...> + <conversion-rule class="target | native"> + // the code + </conversion-rule> + </modify-argument> + + This node is typically used in combination with the replace-type and + remove-argument nodes. The given code is used instead of the generator's + conversion code. + + Writing %N in the code (where N is a number), will insert the name of the + nth argument. Alternatively, %in and %out which will be replaced with the + name of the conversion's input and output variable, respectively. Note the + output variable must be declared explicitly, for example: + + .. code-block:: xml + + <conversion-rule class="native"> + bool %out = (bool) %in; + </conversion-rule> + + .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`. + +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> + +rename to +^^^^^^^^^ + + The 'rename to' node is used to rename a argument and use this new name in the generated code. + + .. code-block:: xml + + <modify-argument> + <rename to='...' /> + </modify-argument> + + +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). + +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 | native" + owner="target | c++ | default" /> + </modify-argument> + + +reference-count +^^^^^^^^^^^^^^^ + + The reference-count tag dictates how an argument should be handled by the + target language reference counting system (if there is any), it also indicates + the kind of relationship the class owning the function being modified has with + the argument. For instance, in a model/view relation a view receiving a model + as argument for a **setModel** method should increment the model's reference + counting, since the model should be kept alive as much as the view lives. + Remember that out hypothetical view could not become parent of the model, + since the said model could be used by other views as well. + The ``action`` attribute specifies what should be done to the argument + reference counting when the modified method is called. It accepts the + following values: + + * add: increments the argument reference counter. + * add-all: increments the reference counter for each item in a collection. + * remove: decrements the argument reference counter. + * set: will assign the argument to the variable containing the reference. + * ignore: does nothing with the argument reference counter + (sounds worthless, but could be used in situations + where the reference counter increase is mandatory + by default). + + .. code-block:: xml + + <modify-argument> + <reference-count action="add|add-all|remove|set|ignore" variable-name="..." /> + </modify-argument> + + + The variable-name attribute specifies the name used for the variable that + holds the reference(s). + + +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 node lets you define the 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 index="1"> + <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. diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_conversionrule.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_conversionrule.rst new file mode 100644 index 000000000..c62d5bbf6 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_conversionrule.rst @@ -0,0 +1,113 @@ +.. _conversion-rule-tag: + +Conversion Rule Tag +------------------- + +.. _conversion-rule: + +conversion-rule +^^^^^^^^^^^^^^^ + + The **conversion-rule** tag specifies how a **primitive-type**, a **container-type**, + or a **value-type** may be converted to and from the native C++ language types to the + target language types. + + .. code-block:: xml + + <value-type> + <conversion-rule> + <native-to-target> + // Code to convert a native value to a target language object. + </native-to-target> + <target-to-native> + <add-conversion type='TARGETTYPEA' check='TARGETTYPEA_CHECK(%in)'> + // Code to convert target language type object of type TARGETTYPEA + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + <add-conversion type='TARGETTYPEB' check='TARGETTYPEB_CHECK(%in)'> + // Code to convert target language type object of type TARGETTYPEB + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + </target-to-native> + </conversion-rule> + </value-type> + + The example above show the structure of a complete conversion rule. Each of the + child tags comprising the conversion rule are described in their own sections + below. + + +.. _native-to-target: + +native-to-target +^^^^^^^^^^^^^^^^ + + The **native-to-target** tag tells how to convert a native C++ value to its + target language equivalent. The text inside the tag is a C++ code the takes + an input value an does what's needed to convert it to the output value. + ``insert-template`` tags may be used to insert commonly repeating code. + + .. code-block:: xml + + <conversion-rule> + <native-to-target> + // Code to convert a native value to a target language object. + </native-to-target> + </conversion-rule> + + Use the replace node to modify the template code. + Notice that the generator must provide type system variables for the input + and output values and types, namely **%in**, **%out**, **%INTYPE** and + **%OUTTYPE**. In the case of container types, **%INTYPE** refers to the + full container type (e.g. **"list<int>"**) and **%INTYPE_0**, **%INTYPE_1**, + **%INTYPE_#**, should be replaced by the types used in the container template + (e.g. **%INTYPE_0** correspondes to **"int"** for **"list<int>"**). + + +.. _target-to-native: + +target-to-native +^^^^^^^^^^^^^^^^ + + The **target-to-native** tag encloses at least one, but usually many, conversions + from target language values to C++ native values. The *optional* attribute + ``replace`` tells if the target language to C++ conversions will be added to, or if + they will replace the implicit conversions collected by *ApiExtractor*. The default + value for it is *yes*. + + + .. code-block:: xml + + <conversion-rule> + <target-to-native replace='yes|no'>\ + // List of target to native conversions meant to replace or expand + // the already existing implicit conversions. + </target-to-native> + </conversion-rule> + + +.. _add-conversion: + +add-conversion +^^^^^^^^^^^^^^ + + Each **add-conversion** tag adds a rule for conversion of a target language type, + indicated by the ``type`` attribute, to the C++ native type represented by the + **primitive-type**, a **container-type**, or **value-type**, to which the parent + **conversion-rule** belongs. + + .. code-block:: xml + + <target-to-native> + <add-conversion type='TARGETTYPE' check='TARGETTYPECHECK(%in)'> + // Code to convert target language type object of type TARGETTYPE_A + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + <target-to-native> + + The ``check`` attribute tells how a target value should be checked to see if it belongs to + the type expected. This attribute is *optional*, for it can be derived from the ``type`` + attribute, but it isn't unusual that some special check is needed. The variables + **%in**, **%out**, **%INTYPE**, **%INTYPE_#**, and **%OUTTYPE**, must be provided by + the generator as in the ``native-to-target`` tag. + diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_documentation.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_documentation.rst new file mode 100644 index 000000000..43f72a1ba --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_documentation.rst @@ -0,0 +1,43 @@ +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: After 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. diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst new file mode 100644 index 000000000..2838c95e1 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst @@ -0,0 +1,132 @@ +.. _manipulating-object-and-value-types: + +Manipulating Object and Value Types +----------------------------------- + +.. _inject-code: + +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 :ref:`object-type`, :ref:`value-type`, + :ref:`modify-function` and :ref:`add-function` nodes. + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end" since="..."> + // 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. + + The ``since`` attribute specify the API version where this code was injected. + +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 + :ref:`object-type` or a :ref:`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). + The ``remove`` attribute is an *optional* attribute, which can mark the field + to be discarded on generation; it has the same purpose of the deprecated tag + :ref:`remove`. + +.. _modify-function: + +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 :ref:`object-type` or a :ref:`value-type` + node. Use the :ref:`modify-argument` node to specify which argument the modification + affects. + + .. code-block:: xml + + <object-type> + <modify-function signature="..." + since="..." + 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 ``since`` attribute specify the API version when this function was modified. + + The ``remove``, ``access`` and ``rename`` attributes are *optional* attributes + for added convenience; they serve the same purpose as the deprecated tags :ref:`remove`, :ref:`access` and :ref:`rename`. + +.. _add-function: + +add-function +^^^^^^^^^^^^ + + The add-function node allows you to add a given function onto the target language, + and it is a child of an :ref:`object-type` or :ref:`value-type` nodes if the + function is suposed to be a method, or :ref:`namespace` and :ref:`typesystem` if + the function is suposed to be a function inside a namespace or a global function. + + Typically when adding a function some code must be injected to provide the function + logic. This can be done using the :ref:`inject-code` node. + + .. code-block:: xml + + <object-type> + <add-function signature="..." return-type="..." access="public | protected" static="yes | no" since="..."/> + </object-type> + + The ``return-type`` attribute defaults to *void*, the ``access`` to *public* and the ``static`` one to *no*. + + The ``since`` attribute specify the API version when this function was added. + +.. _conversion-rule-on-types: + +conversion-rule +^^^^^^^^^^^^^^^ + + The conversion-rule node allows you to write customized code to convert the given argument between the target + language and C++, and is a child of the :ref:`value-type`, :ref:`object-type`, :ref:`primitive-type` and + :ref:`container-type` nodes. + + The code pointed by the file attribute is very tied to the generator using APIExtractor, so it don't follow any + rules, but the generator rules.. + + .. code-block:: xml + + <value-type name="Foo"> + <convertion-rule file="my_converter_implementation.h" since="..."/> + </value-type> + + The ``since`` attribute specify the API version when this conversion rule became valid. + + .. note:: You can also use the conversion-rule node to specify :ref:`how the conversion of a single function argument should be done in a function <conversion-rule>`. + diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_modify_function.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_modify_function.rst new file mode 100644 index 000000000..071cea4f5 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_modify_function.rst @@ -0,0 +1,78 @@ +.. _modifying-functions: + +Modifying Functions +------------------- + +.. _modify-argument: + +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: + +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> + + .. warning:: This tag is deprecated, use the ``remove`` attribute from :ref:`modify-function` tag instead. + +.. _access: + +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> + + .. warning:: This tag is deprecated, use the ``access`` attribute from :ref:`modify-function` tag instead. + +.. _rename: + +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. + + .. warning:: This tag is deprecated, use the ``rename`` attribute from :ref:`modify-function` tag instead. diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_solving_compilation.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_solving_compilation.rst new file mode 100644 index 000000000..81d14a187 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_solving_compilation.rst @@ -0,0 +1,70 @@ +Solving compilation problems +---------------------------- + +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 "*"). + +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 "...". diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_specifying_types.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_specifying_types.rst new file mode 100644 index 000000000..0d24a6d52 --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_specifying_types.rst @@ -0,0 +1,371 @@ +Specifying Types +---------------- + +.. _typesystem: + +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 \*. + +.. _primitive-type: + +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="..." + since="..." + target-name="..." + default-constructor="..." + preferred-conversion="yes | no" /> + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optional, + **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. + + The *optional* **since** value is used to specify the API version of this type. + + 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". + + The *optional* **default-constructor** specifies the minimal constructor + call to build one value of the primitive-type. This is not needed when the + primitive-type may be built with a default constructor (the one without + arguments). + + The *optional* **preferred-conversion** attribute tells how to build a default + instance of the primitive type. It should be a constructor call capable of + creating a instance of the primitive type. Example: a class "Foo" could have + a **preferred-conversion** value set to "Foo()". Usually this attribute is + used only for classes declared as primitive types and not for primitive C++ + types, but that depends on the application using *ApiExtractor*. + + +.. _namespace: + +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="..." + generate="yes | no" + package="..." + since="..." + revision="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". + + The *optional* **generate** attribute is used to inform if you need to prepend + the given namespace into each generated class. Its default value is **yes**. + + The **package** attribute can be used to override the package of the type system. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +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="..." + identified-by-value="..." + since="..." + flags="yes | no" + flags-revision="..." + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" + revision="..." /> + </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*). + + The *optional* **since** value is used to specify the API version of this type. + + The attribute **identified-by-value** helps to specify anonymous enums using the + name of one of their values, which is unique for the anonymous enum scope. + Notice that the **enum-type** tag can either have **name** or **identified-by-value** + but not both. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The **flags-revision** attribute has the same purposes of **revision** attribute but + is used for the QFlag related to this enum. + + +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. + +.. _value-type: + +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 :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <value-type name="..." since="..." + copyable="yes | no" + hash-function="..." + stream="yes | no" + default-constructor="..." + revision="..." /> + </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. + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The *optional* **default-constructor** specifies the minimal constructor + call to build one instance of the value-type. This is not needed when the + value-type may be built with a default constructor (the one without arguments). + Usually a code generator may guess a minimal constructor for a value-type based + on its constructor signatures, thus **default-constructor** is used only in + very odd cases. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +.. _object-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 :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + since="..." + copyable="yes | no" + hash-function="..." + stream="yes | no" + revision="..." /> + </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`. + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +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 :ref:`object-type`. + + .. code-block:: xml + + <typesystem> + <interface-type name="..." + since="..." + package ="..." + default-superclass ="..." + revision="..." /> + </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. + + The *optional* **since** value is used to specify the API version of this interface. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +.. _container-type: + +container-type +^^^^^^^^^^^^^^ + + The container-type node indicates that the given class is a container and + must be handled using one of the conversion helpers provided by attribute **type**. + + .. code-block:: xml + + <typesystem> + <container-type name="..." + since="..." + type ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The **type** + attribute is used to indicate what conversion rule will be applied to the + container. It can be: *list*, *string-list*, *linked-list*, *vector*, *stack*, + *queue*, *set*, *map*, *multi-map*, *hash*, *multi-hash* or *pair*. + + The *optional* **since** value is used to specify the API version of this container. + + +.. _custom-type: + +custom-type +^^^^^^^^^^^ + + The custom-type node simply makes the parser aware of the existence of a target + language type, thus avoiding errors when trying to find a type used in function + signatures and other places. The proper handling of the custom type is meant to + be done by a generator using the APIExractor. + + .. code-block:: xml + + <typesystem> + <custom-type name="..." /> + </typesystem> + + The **name** attribute is the name of the custom type, e.g., "PyObject". + + +.. _function: + +function +^^^^^^^^ + + The function node indicates that the given C++ global function is mapped onto + the target language. + + .. code-block:: xml + + <typesystem> + <function signature="..." rename="..." since="..."/> + </typesystem> + + This tag has some limitations, it doesn't support function modifications, besides you + can't add a function overload using :ref:`add-function` tag to an existent function. + These limitation will be addressed in future versions of ApiExtractor. + + The function tag has two *optional* attributes: **since**, whose value is used to specify + the API version of this function, and **rename**, to modify the function name. + diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_templates.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_templates.rst new file mode 100644 index 000000000..31b155c5a --- /dev/null +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_templates.rst @@ -0,0 +1,55 @@ +.. _using-code-templates: + +Using Code Templates +-------------------- + +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. + + +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``. + |
