[gobject-introspection] Sphinx based user documentation
- From: Christoph Reiter <creiter src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Sphinx based user documentation
- Date: Sat, 16 Jun 2018 15:45:05 +0000 (UTC)
commit 539dfca540759b8a97e6906981d4240ca044af9f
Author: Christoph Reiter <reiter christoph gmail com>
Date: Sun Jun 10 11:24:47 2018 +0200
Sphinx based user documentation
The current output (more or less a straight copy of the wiki) is available
here:
https://gi.readthedocs.io
This contains two changes:
* Converts all (not completely outdated) wiki pages to a sphinx based
documentation.
* Converts the man pages to reST and adds a Makefile for building them
using rst2man. So they can be easily exposed in the sphinx docs.
Goals:
* Have a user focused/compact documentation instead of random wiki pages
with various todo/ideas pages.
* Take advantage of the gitlab MR workflow by
* allowing large documentation changes/refactorings with reviews
* allowing to combine features changes with documentation changes in MRs
docs/g-ir-compiler.1 | 78 +-
docs/g-ir-generate.1 | 66 +-
docs/g-ir-scanner.1 | 251 ++++---
docs/website/.gitignore | 1 +
docs/website/Makefile | 10 +
docs/website/annotations/giannotations.rst | 790 +++++++++++++++++++++
docs/website/annotations/gtkdoc.rst | 170 +++++
docs/website/annotations/index.rst | 10 +
docs/website/architecture.rst | 64 ++
docs/website/buildsystems/autotoolsintegration.rst | 122 ++++
docs/website/buildsystems/index.rst | 10 +
docs/website/buildsystems/meson.rst | 49 ++
docs/website/conf.py | 33 +
docs/website/extra.css | 49 ++
docs/website/goals.rst | 72 ++
docs/website/images/architecture.svg | 120 ++++
docs/website/images/overview.svg | 540 ++++++++++++++
docs/website/index.rst | 71 ++
docs/website/tools/Makefile | 11 +
docs/website/tools/g-ir-compiler.rst | 68 ++
docs/website/tools/g-ir-generate.rst | 54 ++
docs/website/tools/g-ir-scanner.rst | 171 +++++
docs/website/tools/index.rst | 21 +
docs/website/users.rst | 52 ++
docs/website/writingbindableapis.rst | 163 +++++
docs/website/writingbindings/guidelines.rst | 45 ++
docs/website/writingbindings/index.rst | 10 +
docs/website/writingbindings/libgirepository.rst | 15 +
28 files changed, 2965 insertions(+), 151 deletions(-)
---
diff --git a/docs/g-ir-compiler.1 b/docs/g-ir-compiler.1
index c2197b44..65c439bb 100644
--- a/docs/g-ir-compiler.1
+++ b/docs/g-ir-compiler.1
@@ -1,41 +1,77 @@
-.TH "g-ir-compiler" 1
-.nh
+.\" Man page generated from reStructuredText.
+.
+.TH G-IR-COMPILER 1 "" "" ""
.SH NAME
-g-ir-compiler \- typelib compiler.
+g-ir-compiler \- Typelib compiler
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
.SH SYNOPSIS
-.B g-ir-compiler
-[OPTION...] GIRFILE
+.sp
+\fBg\-ir\-compiler\fP [OPTION...] GIRFILE
.SH DESCRIPTION
-g-ir-compiler converts one or more GIR files into one or more typelib.
-The output will be written to standard output unless the --output
-is specified.
+.sp
+g\-ir\-compiler converts one or more GIR files into one or more typelib. The
+output will be written to standard output unless the \fB\-\-output\fP is
+specified.
.SH OPTIONS
+.INDENT 0.0
.TP
-.B \--help
+.B \-\-help
Show help options
.TP
-.B \--output=FILENAME
+.BI \-\-output\fB= FILENAME
Save the resulting output in FILENAME.
.TP
-.B \--verbose
+.B \-\-verbose
Show verbose messages
.TP
-.B \--debug
+.B \-\-debug
Show debug messages
.TP
-.B \--includedir=DIRECTORY
+.BI \-\-includedir\fB= DIRECTORY
Adds a directory which will be used to find includes inside the GIR format.
.TP
-.B \--module=MODULE
+.BI \-\-module\fB= MODULE
FIXME
.TP
-.B \--shared-library=FILENAME
-Specifies the shared library where the symbols in the typelib can be found.
-The name of the library should not contain the ending shared library suffix.
-.TP
+.BI \-\-shared\-library\fB= FILENAME
+Specifies the shared library where the symbols in the typelib can be
+found. The name of the library should not contain the ending shared
+library suffix.
+.UNINDENT
.SH BUGS
-Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues.
-.SH HOMEPAGE and CONTACT
-http://live.gnome.org/GObjectIntrospection
+.sp
+Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP
+.SH HOMEPAGE AND CONTACT
+.sp
+\fI\%http://live.gnome.org/GObjectIntrospection\fP
.SH AUTHORS
+.sp
Mattias Clasen
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/g-ir-generate.1 b/docs/g-ir-generate.1
index ffe4904a..fb07de75 100644
--- a/docs/g-ir-generate.1
+++ b/docs/g-ir-generate.1
@@ -1,29 +1,63 @@
-.TH "g-ir-generate" 1
-.nh
+.\" Man page generated from reStructuredText.
+.
+.TH G-IR-GENERATE 1 "" "" ""
.SH NAME
-g-ir-generate \- typelib generator
+g-ir-generate \- Typelib generator
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
.SH SYNOPSIS
-.B g-ir-generate
-[OPTION...] FILES...
+.sp
+\fBg\-ir\-generate\fP [OPTION...] FILES...
.SH DESCRIPTION
-g-ir-generate is an GIR generator, using the repository API. It generates
-GIR files from a raw typelib or in a shared library (--shlib).
-The output will be written to standard output unless the --output
-is specified.
+.sp
+g\-ir\-generate is an GIR generator, using the repository API. It generates GIR
+files from a raw typelib or in a shared library (\fB\-\-shlib\fP). The output will
+be written to standard output unless the \fB\-\-output\fP is specified.
.SH OPTIONS
+.INDENT 0.0
.TP
-.B \, --help
+.B \-\-help
Show help options
.TP
-.B \, --shlib=FILENAME
+.BI \-\-shlib\fB= FILENAME
The shared library to read the symbols from.
.TP
-.B \, --output=FILENAME
+.BI \-\-output\fB= FILENAME
Save the resulting output in FILENAME.
-.TP
+.UNINDENT
.SH BUGS
-Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues.
-.SH HOMEPAGE and CONTACT
-http://live.gnome.org/GObjectIntrospection
+.sp
+Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP
+.SH HOMEPAGE AND CONTACT
+.sp
+\fI\%http://live.gnome.org/GObjectIntrospection\fP
.SH AUTHORS
+.sp
Mattias Clasen
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/g-ir-scanner.1 b/docs/g-ir-scanner.1
index d38241f1..2078d927 100644
--- a/docs/g-ir-scanner.1
+++ b/docs/g-ir-scanner.1
@@ -1,154 +1,177 @@
-.TH "g-ir-scanner" 1
-.nh
+.\" Man page generated from reStructuredText.
+.
+.TH G-IR-SCANNER 1 "" "" ""
.SH NAME
-g-ir-scanner \- extracting C metadata from sources and headers
+g-ir-scanner \- Extracting C metadata from sources and headers
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
.SH SYNOPSIS
-.B g-ir-scanner
-[OPTION...] FILES...
+.sp
+\fBg\-ir\-scanner\fP [OPTION...] FILES...
.SH DESCRIPTION
-g-ir-scanner is a tool which generates GIR XML files by parsing headers
-and introspecting GObject based libraries.
-It is usually invoked during the normal build step for a project and
-the information is saved to disk and later installed, so that language bindings
-and other applications can use it.
-Header files and source files are passed in as arguments on the command line.
-The suffix determines whether a file be treated as a source file (.c) or a
-header file (.h). Currently only C based libraries are supported by the scanner.
+.sp
+g\-ir\-scanner is a tool which generates GIR XML files by parsing headers and
+introspecting GObject based libraries. It is usually invoked during the normal
+build step for a project and the information is saved to disk and later
+installed, so that language bindings and other applications can use it. Header
+files and source files are passed in as arguments on the command line. The
+suffix determines whether a file be treated as a source file (.c) or a header
+file (.h). Currently only C based libraries are supported by the scanner.
.SH OPTIONS
+.INDENT 0.0
.TP
-.B \--help
+.B \-\-help
Show help options
.TP
-.B \--quiet
+.B \-\-quiet
If passed, do not print details of normal operation.
.TP
-.B \--warn-all
+.B \-\-warn\-all
Display warnings for public API which is not introspectable.
.TP
-.B \--warn-error
+.B \-\-warn\-error
Make warnings be fatal errors.
.TP
-.B \--format=FORMAT
-This parameters decides which the resulting format will be used.
-The default value is gir.
+.BI \-\-format\fB= FORMAT
+This parameters decides which the resulting format will be used. The
+default value is gir.
.TP
-.B \--include=NAME
+.BI \-\-include\fB= NAME
Add the specified introspection dependency to the scanned namespace.
-NAME is of the form NAMESPACE-VERSION, like Gtk-3.0.
+NAME is of the form NAMESPACE\-VERSION, like Gtk\-3.0.
.TP
-.B \--include-uninstalled=PATH
+.BI \-\-include\-uninstalled\fB= PATH
Add the specified introspection dependency to the scanned namespace.
-This differs from \--include in that it takes a file path, and
-does not process the pkg-config dependencies (since they may not
-be installed yet).
+This differs from \fB\-\-include\fP in that it takes a file path, and does not
+process the pkg\-config dependencies (since they may not be installed yet).
.TP
-.B \--add-include-path=PATH
-Add a directory to the path which the scanner uses to find GIR files.
-Can be used multiple times to specify multiple directories
+.BI \-\-add\-include\-path\fB= PATH
+Add a directory to the path which the scanner uses to find GIR files. Can
+be used multiple times to specify multiple directories
.TP
-.B \-i, --library=LIBRARY
+.BI \-i\fP,\fB \-\-library\fB= LIBRARY
Specifies a library that will be introspected. This means that the
-*_get_type() functions in it will be called for GObject data types.
-The name of the library should not contain the leading lib prefix nor
-the ending shared library suffix.
+*_get_type() functions in it will be called for GObject data types. The
+name of the library should not contain the leading lib prefix nor the
+ending shared library suffix.
.TP
-.B \-L, --library-path=PATH
-Include this directory when searching for a library.
-This option can be specified multiple times to include more than one
-directory to look for libraries in.
+.BI \-L\fP,\fB \-\-library\-path\fB= PATH
+Include this directory when searching for a library. This option can be
+specified multiple times to include more than one directory to look for
+libraries in.
.TP
-.B \-Idirectory
+.BI \-I\fB directory
Include this directory in the list of directories to be searched for
-header files. You need to pass to the scanner all the directories
-you'd normally pass to the compiler when using the specified source
-files.
+header files. You need to pass to the scanner all the directories you\(aqd
+normally pass to the compiler when using the specified source files.
.TP
-.B \-n, --namespace=NAME
+.BI \-n\fP,\fB \-\-namespace\fB= NAME
The namespace name. This name should be capitalized, eg the first letter
should be upper case. Examples: Gtk, Clutter, WebKit.
.TP
-.B \--no-libtool
-Disable usage of libtool for compiling stub introspection binary. Use this
+.B \-\-no\-libtool
+Disable usage of libtool for compiling stub introspection binary. Use this
if your build system does not require libtool.
.TP
-.B \--libtool
-Full path to libtool executable. Typically used for Automake systems.
+.B \-\-libtool
+Full path to libtool executable. Typically used for Automake systems.
.TP
-.B \--nsversion=VERSION
-The namespace version. For instance 1.0. This is usually the platform version,
-eg 2.0 for Gtk+, not 2.12.7.
+.BI \-\-nsversion\fB= VERSION
+The namespace version. For instance 1.0. This is usually the platform
+version, eg 2.0 for Gtk+, not 2.12.7.
.TP
-.B \-p, --program=PROGRAM
+.BI \-p\fP,\fB \-\-program\fB= PROGRAM
Specifies a binary that will be introspected. This means that the
-*_get_type() functions in it will be called for GObject data types.
-The binary must be modified to take a --introspect-dump= option, and
-to pass the argument to this function to g_irepository_dump.
+*_get_type() functions in it will be called for GObject data types. The
+binary must be modified to take a \fB\-\-introspect\-dump=\fP option, and to pass
+the argument to this function to g_irepository_dump.
.TP
-.B \--program-arg=ARG
+.BI \-\-program\-arg\fB= ARG
Additional argument to pass to program for introspection.
.TP
-.B \--identifier-prefix=PREFIX
-This option may be specified multiple times. Each one
-gives a prefix that will be stripped from all C identifiers.
-If none specified, the namespace will be used.
-Eg, an identifier prefix of
-.B Foo
-will export the identifier
-.B typdef struct _FooBar FooBar;
-as
-.B Foo.Bar.
-.TP
-.B \--symbol-prefix=PREFIX
-This option may be specified multiple times. Each one
-gives a prefix that will be stripped from all C symbols.
-Eg, an symbol prefix of
-.B foo
-will export the symbol
-.B foo_bar_do_something
-as
-.B Foo.Bar.do_something.
-.TP
-.B \--accept-unprefixed
-If specified, the scanner will accept identifiers and symbols which
-do not match the namespace prefix. Try to avoid using this if possible.
-.TP
-.B \--output=FILENAME
-Name of the file to output. Normally namespace + format extension.
-Eg, GLib-2.0.gir.
-.TP
-.B \--pkg=PACKAGE
-List of pkg-config packages to get compiler and linker flags from.
-This option can be specified multiple times to include flags from
-several pkg-config packages.
-.TP
-.B \--pkg-export=PACKAGE
-List of pkg-config packages that are provided by the generated gir.
-This option can be specified multiple times if the gir provides more
-packages.
-If not specified, the packages specified with --pkg= will be used.
-.TP
-.B \--verbose
+.BI \-\-identifier\-prefix\fB= PREFIX
+This option may be specified multiple times. Each one gives a prefix that
+will be stripped from all C identifiers. If none specified, the namespace
+will be used. Eg, an identifier prefix of Foo will export the identifier
+typdef struct _FooBar FooBar; as Foo.Bar.
+.TP
+.BI \-\-symbol\-prefix\fB= PREFIX
+This option may be specified multiple times. Each one gives a
+prefix that will be stripped from all C symbols. Eg, an symbol
+prefix of foo will export the symbol foo_bar_do_something as
+Foo.Bar.do_something.
+.TP
+.B \-\-accept\-unprefixed
+If specified, the scanner will accept identifiers and symbols which do not
+match the namespace prefix. Try to avoid using this if possible.
+.TP
+.BI \-\-output\fB= FILENAME
+Name of the file to output. Normally namespace + format extension. Eg,
+GLib\-2.0.gir.
+.TP
+.BI \-\-pkg\fB= PACKAGE
+List of pkg\-config packages to get compiler and linker flags from. This
+option can be specified multiple times to include flags from several
+pkg\-config packages.
+.TP
+.BI \-\-pkg\-export\fB= PACKAGE
+List of pkg\-config packages that are provided by the generated gir. This
+option can be specified multiple times if the gir provides more packages.
+If not specified, the packages specified with \fB\-\-pkg=\fP will be used.
+.TP
+.B \-\-verbose
Be verbose, include some debugging information.
-.TP
+.UNINDENT
.SH ENVIRONMENT VARIABLES
-The g-ir-scanner uses the XDG_DATA_DIRS variable to check for dirs,
-the girs are located in XDG_DATA_DIRS/gir-1.0. It is normally
-set on a distribution so you shouldn't need to set it yourself.
-
-The variable GI_SCANNER_DISABLE_CACHE ensures that the scanner will
-not write cache data to $HOME.
-
-The variable GI_SCANNER_DEBUG can be used to debug issues in the build-system that
-involve g-ir-scanner. When it is set to 'save-temps', then g-ir-scanner will not remove
-temporary files and directories after it terminates.
-
-The variable GI_HOST_OS can be used to control the OS name on the
-host that runs the scanner. It has the same semantics as the Python
-os.name property.
+.sp
+The g\-ir\-scanner uses the \fBXDG_DATA_DIRS\fP variable to check for dirs, the
+girs are located in \fBXDG_DATA_DIRS/gir\-1.0\fP\&. It is normally set on a
+distribution so you shouldn\(aqt need to set it yourself.
+.sp
+The variable \fBGI_SCANNER_DISABLE_CACHE\fP ensures that the scanner will not
+write cache data to \fB$HOME\fP\&.
+.sp
+The variable \fBGI_SCANNER_DEBUG\fP can be used to debug issues in the
+build\-system that involve g\-ir\-scanner. When it is set to \fBsave\-temps\fP, then
+g\-ir\-scanner will not remove temporary files and directories after it
+terminates.
+.sp
+The variable \fBGI_HOST_OS\fP can be used to control the OS name on the host
+that runs the scanner. It has the same semantics as the Python \fBos.name\fP
+property.
.SH BUGS
-Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues.
-.SH HOMEPAGE and CONTACT
-http://live.gnome.org/GObjectIntrospection
+.sp
+Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP
+.SH HOMEPAGE AND CONTACT
+.sp
+\fI\%http://live.gnome.org/GObjectIntrospection\fP
.SH AUTHORS
+.sp
Johan Dahlin
-
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/website/.gitignore b/docs/website/.gitignore
new file mode 100644
index 00000000..e35d8850
--- /dev/null
+++ b/docs/website/.gitignore
@@ -0,0 +1 @@
+_build
diff --git a/docs/website/Makefile b/docs/website/Makefile
new file mode 100644
index 00000000..928ef6a3
--- /dev/null
+++ b/docs/website/Makefile
@@ -0,0 +1,10 @@
+all: _build
+
+_build: Makefile *.rst images/*.svg */*.rst conf.py
+ python3 -m sphinx -b html . _build
+
+linkcheck:
+ python3 -m sphinx -b linkcheck -n . _build
+
+clean:
+ rm -Rf _build
diff --git a/docs/website/annotations/giannotations.rst b/docs/website/annotations/giannotations.rst
new file mode 100644
index 00000000..cacc20de
--- /dev/null
+++ b/docs/website/annotations/giannotations.rst
@@ -0,0 +1,790 @@
+GObject-Introspection annotations
+---------------------------------
+
+Symbol visibility
+~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(skip)``
+ - identifier
+ - Omit the symbol from the introspected output.
+ - :commit:`v0.6.4 <7549c8053d0229a12d9196cc8abae54a01a555d0>`
+ :bzbug:`556628`
+ * -
+ - paremeters, return value
+ - Indicate that the parameter or return value is only useful in C and
+ should be skipped.
+ - :commit:`v1.29.0 <9c6797e0478b5025c3f2f37b1331c1328cf34f4d>`
+ :bzbug:`649657`
+ * - ``(rename-to SYMBOL)``
+ - identifier
+ - Rename the original symbol's name to ``SYMBOL``. If ``SYMBOL`` resolves
+ to a symbol name that is already used, the original binding for that
+ name is removed.
+ - :commit:`v0.6.3 <23e6fa6993c046de032598127ea48d4a7ee00935>`
+ :bzbug:`556475`
+
+
+Memory and lifecycle management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(transfer MODE)``
+ - identifier (only properties)
+ - Transfer ownership for the property, (see below)
+ - :commit:`v0.9.0 <22ae017ffd3052c0b81822b2ca6e41626b76b9c4>`
+ :bzbug:`620484`
+ * -
+ - parameters, return value
+ - Transfer mode for the parameter or return value (see below).
+ - v0.5.0 unknown
+
+Transfer modes:
+
+* ``none``: the recipient does not own the value
+* ``container``: the recipient owns the container, but not the elements.
+ (Only meaningful for container types.)
+* ``full``: the recipient owns the entire value. For a refcounted type,
+ this means the recipient owns a ref on the value. For a container type,
+ this means the recipient owns both container and elements.
+* ``floating``: alias for none, can be used for floating objects.
+
+``container`` is usually a pointer to a list or hash table, eg GList, GSList,
+GHashTable etc.
+
+``elements`` is what is contained inside the list: integers, strings, GObjects
+etc.
+
+
+Support for GObject objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(constructor)``
+ - identifier
+ - The annotated symbol should not become available as a static methods
+ but as a constructor.
+ - :commit:`v0.10.2 <2c36790c>`
+ :bzbug:`561264`
+ * - ``(method)``
+ - identifier
+ - This function is a method.
+ - :commit:`v0.10.2 <09bca85d>`
+ :bzbug:`639945`
+ * - ``(virtual SLOT)``
+ - identifier
+ - This function is the invoker for a virtual method.
+ - :commit:`v0.6.3 <fdbe3cc3>`
+ :bzbug:`557383`
+
+
+Support for GObject closures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(destroy)``
+ - parameters
+ - The parameter is a "``destroy_data``" for callbacks.
+ - :commit:`v0.6.3 <cf7621f3>`
+ :bzbug:`574284`
+ * - ``(destroy DESTROY)``
+ - parameters
+ - The parameter is a "``destroy_data``" for callbacks, the
+ ``DESTROY`` option points to a paramter name other than
+ ``destroy_data``.
+ -
+ * - ``(closure)``
+ - parameters
+ - The parameter is a "``user_data``" for callbacks.
+ Many bindings can pass ``NULL`` here.
+ -
+ * - ``(closure CLOSURE)``
+ - parameters
+ - The parameter is a "``user_data``" for callbacks, the ``CLOSURE`` option
+ points to a different parameter that is the actual callback.
+ -
+
+
+Support for non-GObject fundamental objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(ref-func FUNC)``
+ - identifier
+ - ``FUNC`` is the function used to ref a struct, must be a GTypeInstance
+ - :commit:`v0.9.2 <1e9822c7>`
+ :bzbug:`568913`
+ * - ``(unref-func FUNC)``
+ - identifier
+ - ``FUNC`` is the function used to unref a struct, must be a GTypeInstance
+ -
+ * - ``(get-value-func FUNC)``
+ - identifier
+ - ``FUNC`` is the function used to convert a struct from a GValue,
+ must be a GTypeInstance
+ -
+ * - ``(set-value-func FUNC)``
+ - identifier
+ - ``FUNC`` is the function used to convert from a struct to a GValue,
+ must be a GTypeInstance
+ -
+
+
+Type signature
+~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(nullable)``
+ - parameters, return value
+ - Indicates that ``NULL`` may be a valid value for a parameter
+ (in, out, inout), or return value (though note that return values which
+ are only ``NULL`` when throwing an error should not be annotated as
+ ``(nullable)``).
+ - :commit:`1.42 <1459ff3e>`
+ :bzbug:`660879`
+ * - ``(not nullable)``
+ - parameters, return value
+ - Indicates that ``NULL`` is not a valid value for a parameter
+ (in, out, inout), or return value.
+ - :commit:`1.48 <10cb665f>`
+ :bzbug:`729660`
+ * - ``(optional)``
+ - parameters
+ - For ``(out)`` or ``(inout)`` parameters, signifies that the caller
+ can pass ``NULL`` to ignore this output parameter.
+ - :commit:`1.42 <1459ff3e>`
+ :bzbug:`660879`
+ * - ``(in)``
+ - parameters
+ - In parameter.
+ - v0.5.0
+ unknown
+ * - ``(out)``
+ - parameters
+ - Out parameter (automatically determine allocation).
+ - v0.5.0
+ unknown
+ * - ``(out caller-allocates)``
+ - parameters
+ - Out parameter, where the calling code must allocate storage.
+ - :commit:`v0.6.13 <5589687a>`
+ :bzbug:`604749`
+ * - ``(out callee-allocates)``
+ - parameters
+ - Out parameter, where the receiving function must allocate storage.
+ -
+ * - ``(inout)``
+ - parameters
+ - In/out parameter.
+ - v0.5.0
+ unknown
+ * - ``(type TYPE)``
+ - identifier
+ - Override the default type, used for properties
+ - :commit:`v0.6.2 <6de1b296>`
+ :bzbug:`546739`
+ * -
+ - parameters, return value
+ - override the parsed C type with given type
+ -
+ * - ``(array)``
+ - parameters, return value
+ - Arrays.
+ - v0.5.0
+ unknown
+ * - ``(array fixed-size=N)``
+ - parameters, return value
+ - array of fixed length N
+ - v0.5.0
+ unknown
+ * - ``(array length=PARAM)``
+ - parameters, return value
+ - array, fetch the length from parameter PARAM
+ - v0.5.0
+ unknown
+ * - ``(array zero-terminated=1)``
+ - parameters, return value
+ - array which is NULL terminated
+ - :commit:`v0.6.0 <d15f8cde>`
+ :bzbug:`557786`
+ * - ``(element-type TYPE)``
+ - parameters, return value
+ - Specify the type of the element inside a container.
+ Can be used in combination with (array).
+ - v0.5.0
+ unknown
+ * - ``(element-type KTYPE VTYPE)``
+ - parameters, return value
+ - Specify the types of the keys and values in a dictionary-like container
+ (eg, ``GHashTable``).
+ - v0.5.0
+ unknown
+ * - ``(foreign)``
+ - identifier
+ - The annotated symbol is a foreign struct, meaning it is not available
+ in a g-i supported library.
+ - :commit:`v0.6.12 <1edeccd2>`
+ :bzbug:`619450`
+ * - ``(scope TYPE)``
+ - parameters
+ - The parameter is a callback, the ``TYPE`` option indicates the lifetime
+ of the call. It is mainly used by language bindings wanting to know when
+ the resources required to do the call (for instance ffi closures) can be
+ freed.
+ - :commit:`v0.6.2 <bc88ef7b>`
+ :bzbug:`556489`
+
+Scope types:
+
+* ``call`` (default) - Only valid for the duration of the call.
+ Can be called multiple times during the call.
+* ``async`` - Only valid for the duration of the first callback invocation.
+ Can only be called once.
+* ``notified`` - valid until the GDestroyNotify argument is called.
+ Can be called multiple times before the GDestroyNotify is called.
+
+An example of a function using the ``call`` scope is ``g_slist_foreach()``.
+For ``async`` there is ``g_file_read_async()`` and for notified
+``g_idle_add_full()``.
+
+Default Annotations: To avoid having the developers annotate everything the
+introspection framework is providing sane default annotation values for a
+couple of situations:
+
+* ``(in)`` parameters: ``(transfer none)``
+* ``(inout)`` and ``(out)`` parameters: ``(transfer full)``
+
+ * if ``(caller allocates)`` is set: ``(transfer none)``
+
+* ``gchar*`` means ``(type utf8)``
+* return values: ``(transfer full)``
+
+ * ``gchar*`` means ``(type utf8) (transfer full)``
+ * ``const gchar*`` means ``(type utf8) (transfer none)``
+ * ``GObject*`` defaults to ``(transfer full)``
+
+
+Data annotations
+~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(value VALUE)``
+ - identifier
+ - Used to override constants for defined values,
+ VALUE contains the evaluated value
+ - v0.5.0
+ unknown
+ * - ``(attributes my.key=val my.key2)``
+ - identifier, parameters, return value
+ - Attributes are free-form "key=value" annotations. When present, at least
+ one key has to be specified. Assigning values to keys is optional.
+ - :commit:`v0.9.0 <11cfe386>`
+ :bzbug:`571548`
+
+
+Deprecated GObject-Introspection annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 10 1
+
+ * - Annotation
+ - Description
+ - Since
+ * - ``(null-ok)``
+ - Replaced by ``(allow-none)``
+ - :commit:`v0.6.0 <dc651812>`
+ :bzbug:`557405`
+ * - ``(in-out)``
+ - Replaced by ``(inout)``
+ - :commit:`1.39.0 <a2b22ce7>`
+ :bzbug:`688897`
+ * - ``(allow-none)``
+ - Replaced by ``(nullable)`` and ``(optional)``
+ - :commit:`1.42 <1459ff3e>`
+ :bzbug:`660879`
+
+
+Possible future GObject-Introspection annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These proposed additions are currently being discussed and in various stages
+of development.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10 1
+
+ * - Annotation
+ - Applies to
+ - Description
+ - Since
+ * - ``(default VALUE)``
+ - parameters
+ - Default value for a parameter.
+ - :bzbug:`558620`
+ * - ``(error-domains DOM1 DOM2)``
+ - parameters
+ - Typed errors, similar to ``throws`` in Java.
+ - unknown
+
+
+Default Basic Types
+-------------------
+
+Basic types:
+
+* gpointer: pointer to anything
+* gboolean:boolean
+* gint[8,16,32,64]: integer
+* guint[8,16,32,64]: unsigned integer
+* glong: long
+* gulong: unsigned long
+* GType: a gtype
+* gfloat: float
+* gdouble: double
+* utf8: string encoded in UTF-8, not containing any embedded nuls
+* filename: filename string (see below)
+* guint8 array: binary data
+
+Filename type:
+
+The filename type represents an utf-8 string on Windows and a zero terminated
+guint8 array on Unix. It should be used for filenames, environment variables
+and process arguments.
+
+
+Reference to Object Instances
+-----------------------------
+
+Instances:
+
+* Object: a GObject instance
+* Gtk.Button: a Gtk.Button instance
+
+
+Examples
+--------
+
+Transfer
+~~~~~~~~
+
+::
+
+ /**
+ * mylib_get_constant1:
+ *
+ * Returns: (transfer full): a constant, free when you used it
+ */
+ gchar *
+ mylib_get_constant1 (void)
+ {
+ return g_strdup("a constant");
+ }
+
+::
+
+ /**
+ * mylib_get_constant2:
+ *
+ * Returns: (transfer none): another constant
+ */
+ const gchar *
+ mylib_get_string2 (void)
+ {
+ return "another constant";
+ }
+
+::
+
+ /**
+ * mylib_get_string_list1:
+ *
+ * Returns: (element-type utf8) (transfer full): list of constants,
+ * free the list with g_slist_free and the elements with g_free when done.
+ */
+ GSList *
+ mylib_get_string_list1 (void)
+ {
+ GSList *l = NULL;
+ l = g_slist_append (l, g_strdup ("foo"));
+ l = g_slist_append (l, g_strdup ("bar"));
+ return l;
+ }
+
+::
+
+ /**
+ * mylib_get_string_list2:
+ *
+ * Returns: (element-type utf8) (transfer container): list of constants
+ * free the list with g_slist_free when done.
+ */
+ GSList *
+ mylib_get_string_list2 (void)
+ {
+ GSList *l = NULL;
+ l = g_slist_append (l, "foo");
+ l = g_slist_append (l, "bar");
+ return l;
+ }
+
+
+Array length
+~~~~~~~~~~~~
+
+::
+
+ /**
+ * gtk_list_store_set_column_types:
+ * @store: a #GtkListStore
+ * @n_columns: Length of @types
+ * @types: (array length=n_columns): List of types
+ */
+ void
+ gtk_list_store_set_column_types (GtkListStore *list_store,
+ gint n_columns,
+ GType *types);
+
+
+Nullable parameters
+~~~~~~~~~~~~~~~~~~~
+
+A number of things are nullable by convention, which means that you do not
+have to add a ``(nullable)`` annotation to your code for them to be marked as
+nullable in a GIR file. If you need to mark a parameter or return value as not
+nullable, use ``(not nullable)`` to override the convention. Conventionally,
+the following are automatically nullable:
+
+* ``(closure)`` parameters and their corresponding user data parameters
+* ``gpointer`` parameters and return types, unless also annotated with
+ ``(type)``
+
+::
+
+ /**
+ * gtk_link_button_new_with_label:
+ * @uri: A URI
+ * @label: (nullable): A piece of text or NULL
+ */
+ GtkWidget *
+ gtk_link_button_new_with_label (const gchar *uri,
+ const gchar *label);
+
+::
+
+ /**
+ * g_source_add_unix_fd:
+ * @source: a #GSource
+ * @fd: the fd to monitor
+ * @events: an event mask
+ *
+ * Returns: (not nullable): an opaque tag
+ */
+ gpointer
+ g_source_add_unix_fd (GSource *source,
+ gint fd,
+ GIOCondition events);
+
+ /**
+ * g_source_remove_unix_fd:
+ * @source: a #GSource
+ * @tag: (not nullable): the tag from g_source_add_unix_fd()
+ */
+ void
+ g_source_remove_unix_fd (GSource *source,
+ gpointer tag);
+
+
+G(S)List contained types
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /**
+ * gtk_container_get_children:
+ * @container: A #GtkContainer
+ *
+ * Returns: (element-type Gtk.Widget) (transfer container): List of #GtkWidget
+ */
+ GList*
+ gtk_container_get_children (GtkContainer *container);
+
+::
+
+ /**
+ * FooBar:alist: (type GSList(NiceObj))
+ *
+ * This property is a GSList of NiceObj GOjects.
+ */
+ g_object_class_install_property (object_class,
+ FOO_BAR_PROP_ALIST,
+ g_param_spec_pointer ("alist",
+ "Alist",
+ "A list of nice objects",
+ G_PARAM_READWRITE));
+
+
+Direction
+~~~~~~~~~
+
+::
+
+ /**
+ * gtk_widget_get_size_request:
+ * @width: (out): Int to store width in
+ * @height: (out): Int to store height in
+ */
+
+
+Out parameters
+~~~~~~~~~~~~~~
+
+This is a callee-allocates example; the (out) annotation automatically infers
+this from the fact that there's a double indirection on a structure parameter.
+
+
+::
+
+ typedef struct _FooSubObj FooSubObj
+
+ /**
+ * foo_obj_get_sub_obj:
+ * @obj: A #FooObj
+ * @subobj: (out): A #FooSubObj
+ *
+ * Get a sub object.
+ */
+ void
+ foo_obj_get_sub_obj (FooObj *obj,
+ FooSubObj **subobj)
+ {
+ *subobj = foo_sub_object_new ();
+ }
+
+This is a caller-allocates example; the (out) annotation automatically infers
+this from the fact that there's only a single indirection on a structure
+parameter.
+
+::
+
+ typedef struct _FooIter FooIter;
+
+ /**
+ * foo_obj_get_iter:
+ * @obj: A #FooObj
+ * @iter: (out): An iterator, will be initialized
+ *
+ * Get an iterator.
+ */
+ void
+ foo_obj_get_iter (FooObj *obj,
+ FooIter *iter)
+ {
+ iter->state = 0;
+ }
+
+An example which demonstrates an (optional) parameter: an (out) parameter
+where the caller can pass NULL if they don’t want to receive the (out) value.
+
+::
+
+ /**
+ * g_file_get_contents:
+ * @filename: name of a file to read contents from, in the GLib file name encoding
+ * @contents: (out): location to store an allocated string, use g_free() to free the returned string
+ * @length: (out) (optional): location to store length in bytes of the contents, or NULL
+ * @error: return location for a GError, or NULL
+ *
+ * [...]
+ *
+ * Returns: TRUE on success, FALSE if an error occurred
+ */
+ gboolean g_file_get_contents (const gchar *filename,
+ gchar **contents,
+ gsize *length,
+ GError **error);
+
+ /* this is valid because length has (optional) */
+ g_file_get_contents ("/etc/motd", &motd, NULL, &error); // VALID
+ /* but this is not valid, according to those annotations */
+ g_file_get_contents ("/etc/motd", NULL, NULL, &error); // NOT VALID
+
+
+g_hash_table_iter_next() demonstrates the difference between (nullable) and
+(optional) for (out) parameters. For an (out) parameter, (optional) indicates
+that NULL may be passed by the caller to indicate they don’t want to receive
+the (out) value. (nullable) indicates that NULL may be passed out by the
+callee as the returned value.
+
+::
+
+ /**
+ * g_hash_table_iter_next:
+ * @iter: an initialized #GHashTableIter
+ * @key: (out) (optional): a location to store the key
+ * @value: (out) (optional) (nullable): a location to store the value
+ *
+ * [...]
+ *
+ * Returns: %FALSE if the end of the #GHashTable has been reached.
+ */
+ gboolean
+ g_hash_table_iter_next (GHashTableIter *iter,
+ gpointer *key,
+ gpointer *value);
+
+ /* this is valid because value and key have (optional) */
+ g_hash_table_iter_next (iter, NULL, NULL);
+
+ gpointer key, value;
+ g_hash_table_iter_next (iter, &key, &value);
+
+ if (value == NULL)
+ /* this is valid because value has (nullable) */
+ if (key == NULL)
+ /* this is NOT VALID because key does not have (nullable) */
+
+
+Rename to
+~~~~~~~~~
+
+Rename to is an advisory annotation. It's not required to fulfill the advisory
+when generating or making a language binding. The way it is currently
+implemented, if you rename a function to a name already in use, it will remove
+the other binding. This is useful to eliminate unwanted/deprecated functions
+from the binding.
+
+Another (currently unimplemented) use for the rename annotation would be
+overloading; for example, overloading of constructors or, like in this
+example, overloading a method to be both an asynchronous and a synchronous one
+(depending on the amount and what kind of parameters).
+
+::
+
+ /**
+ * my_type_perform_async: (rename-to my_type_perform)
+ * @self: The this ptr
+ * @data: data
+ * @callback: callback when async operation finished
+ * @user_data: user_data for @callback
+ *
+ * Asynchronously perform
+ **/
+ void
+ my_type_perform_async (MyType *self, gpointer data,
+ GFunc callback,
+ gpointer user_data);
+
+ /**
+ * my_type_perform:
+ * @self: The this ptr
+ * @data: data
+ *
+ * Perform
+ **/
+ void
+ my_type_perform (MyType *self, gpointer data);
+
+In a language supporting method overloading, because we advised to rename to
+perform, and because we have another perform already, this could be bound like
+this:
+
+::
+
+ class MyType {
+ public void perform (Pointer data) { }
+ public void perform (Pointer data, GFunc callback, Pointer user_data) { }
+ }
+
+However, currently the generated gir/typelib will only contain information
+about my_type_perform_async, which will shadow (ie, remove) the binding of
+my_type_perform.
+
+
+Attributes
+~~~~~~~~~~
+
+Attributes are arbitrary key/value pairs that can be attached to almost any
+item including classes, methods, signals, properties, parameters and return
+values. These attributes appear in both the .gir and the .typelib files.
+Attributes can serve as a mechanism for software higher in the toolchain.
+Attributes are name-spaced using dot as a separator. At least one dot must
+appear in the key name.
+
+::
+
+ /**
+ * my_frobnicator_poke_path: (attributes gdbus.method PokePath)
+ * @frobnicator: A #MyFrobnicator
+ * @object_path: (gdbus.signature o): An object path.
+ *
+ * Manipulate an object path.
+ *
+ * Returns: (gdbus.signature o): A new object path. Free with g_free().
+ */
+ gchar *
+ my_frobnicator_poke_path (MyFrobnicator *frobnicator,
+ const gchar *object_path)
+
+
+Constants
+~~~~~~~~~
+
+::
+
+ /**
+ * MY_CONSTANT: (value 100)
+ * A constant.
+ */
+ #define MY_CONSTANT 10 * 10
diff --git a/docs/website/annotations/gtkdoc.rst b/docs/website/annotations/gtkdoc.rst
new file mode 100644
index 00000000..14057366
--- /dev/null
+++ b/docs/website/annotations/gtkdoc.rst
@@ -0,0 +1,170 @@
+=====================
+GTK-Doc Format Primer
+=====================
+
+GObject-Introspection annotations are built on top of GTK-Doc comment
+blocks. These are plain old C comment blocks, but formatted in a special
+way. Each GTK-Doc comment block starts with a ``/**`` on its own line
+end ends with ``*/``, again on its own line.
+
+The basic format of a GTK-Doc comment block looks like this:
+
+::
+
+ /**
+ * identifier_name: (annotations)
+ * @parameter_name: (annotations): description
+ *
+ * symbol description
+ *
+ * tag_name: (annotations): description
+ */
+
+As we can see, a GTK-Doc comment block can be broken down into a couple of
+parts. Each part is built out of one or more fields, separated by a ``:``
+character. Each part has to start on its own line. Fields cannot span multiple
+lines except the various ``description`` fields.
+
+The order in which parts are written is important. For example, putting a
+``tag`` part before the ``symbol description`` part is invalid as it would
+result in the symbol description to be mistaken for the tag description.
+
+In the above example we have:
+
+* the start of a GTK-Doc comment block on line 1
+* the identifier part on line 2
+* a parameter part on line 3
+* the symbol description on line 5
+* a tag part on line 7
+* the end of the comment block on line 8
+
+identifier part
+~~~~~~~~~~~~~~~
+
+::
+
+ /**
+ * identifier_name: (annotations)
+ * ...
+ */
+
+The identifier part is required as it identifies the symbol you want to
+annotate. It is always written on the line immediately following the start of
+your GTK-Doc comment block (``/**``).
+
+The ``identifier`` part is constructed from:
+
+* a required ``identifier_name`` field
+
+ * different kinds of symbols that can be documented and annotated are
+ described in the GTK-Doc manual.
+
+* an optional ``annotations`` field
+
+parameter part
+~~~~~~~~~~~~~~
+
+::
+
+ /**
+ * ...
+ * @parameter_name: (annotations): description
+ * ...
+ */
+
+The ``parameter`` part is optional. This means that there can be 0 or more
+parameters, depending on the symbol you are annotating.
+
+``parameter`` parts are constructed from:
+
+* a required ``parameter_name`` which starts with a ``@`` character
+
+ * this name should correspond with the parameter name of you function's
+ signature.
+
+* an optional ``annotations`` field
+* a required description field (can be "empty")
+
+ * can contain a single paragraph (multiple lines but no empty lines) of
+ text.
+
+Note that multiple ``parameter`` parts are never separated by an empty line.
+
+symbol description part
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /**
+ * ...
+ *
+ * symbol description
+ * ...
+ */
+
+The ``symbol description`` part is optional. When present, it must always be
+preceded with an empty line. It can contain multiple paragraphs (multiple
+lines and empty lines) describing what the function, property, signal, enum or
+constant does.
+
+tag part
+~~~~~~~~
+
+::
+
+ /**
+ * ...
+ * tag_name: (annotations)||value: description
+ * ...
+ */
+
+The ``tag`` part is optional. There can be 0 or more tags, depending on the
+symbol you are annotating.
+
+``tag`` parts are constructed from:
+
+* a required ``tag_name``
+
+ * There are only four valid tags: ``Returns``, ``Since``, ``Deprecated``,
+ and ``Stability``.
+
+* an optional ``annotations`` field (``Returns``)
+ **OR**
+ an optional ``value`` field (``Since``, ``Deprecated``, and ``Stability``)
+* a required description field (can be "empty")
+
+ * can contain multiple paragraphs (multiple lines and empty lines) of text.
+
+``tag`` parts can safely be preceded or followed by an empty line.
+
+Tags taking an optional ``value`` field accept the following values:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 1 1 10
+
+ * - Tag
+ - Value field
+ - Description
+ * - ``Since``
+ - ``VERSION``
+ - This symbol was added in version ``VERSION``.
+ * - ``Deprecated``
+ - ``VERSION``
+ - This symbol has been deprecated since version ``VERSION``.
+ * - ``Stability``
+ - ``Stable``, ``Unstable``, or ``Private``
+ - An informal description of the stability level of this symbol.
+
+
+GTK-Doc support
+---------------
+
+If GTK-Doc doesn't seem to understand your introspection annotations, you may
+need to do two things:
+
+#. make sure you are running GTK-Doc >= v1.12 (also try latest version from
+ git)
+#. add ``<xi:include href="xml/annotation-glossary.xml"><xi:fallback/></xi:include>``
+ to your master GTK-Doc document; e.g. see the end of `tester-docs.xml
+ <https://gitlab.gnome.org/GNOME/gtk-doc/blob/master/tests/gobject/docs/tester-docs.xml>`__
diff --git a/docs/website/annotations/index.rst b/docs/website/annotations/index.rst
new file mode 100644
index 00000000..8a522a7d
--- /dev/null
+++ b/docs/website/annotations/index.rst
@@ -0,0 +1,10 @@
+===========
+Annotations
+===========
+
+.. toctree::
+ :titlesonly:
+ :maxdepth: 1
+
+ gtkdoc
+ giannotations
diff --git a/docs/website/architecture.rst b/docs/website/architecture.rst
new file mode 100644
index 00000000..dce8a0a0
--- /dev/null
+++ b/docs/website/architecture.rst
@@ -0,0 +1,64 @@
+============
+Architecture
+============
+
+.. figure:: images/architecture.svg
+ :align: center
+
+
+::
+
+ BUILD TIME:
+
+ +-----------------------------------------------------------+
+ | foo.c |
+ | foo.h |
+ | |
+ | Library sources, with type annotations |
+ +-----------------------------------------------------------+
+ | |
+ gcc g-ir-scanner
+ | |
+ | V
+ | +------------------------+
+ | | Foo.gir |
+ | | |
+ | | <GI-name>.gir |
+ | | |
+ | | XML file |
+ | | |
+ | | Invocation information |
+ | | Required .gir files |
+ | | API docs |
+ | | |
+ | +------------------------+
+ | |
+ | g-ir-compiler
+ | |
+ DEPLOYMENT TIME: |
+ | |
+ V V
+ +-----------------------------+ +---------------------------+
+ | libfoo.so | | Foo.typelib |
+ | | | |
+ | | | Binary version of the |
+ | ELF file | | invocation info and |
+ | | | required .typelib files |
+ | Machine code, plus | +---------------------------+
+ | dynamic linkage information | A
+ | (DWARF debug data, etc) | |
+ +-----------------------------+ |
+ A |
+ | +---------------------------+
+ | | libgirepository.so |
+ +-----------+ | |
+ | libffi.so | | Can read typelibs and |
+ | |<-------+------>| present them in a |
+ +-----------+ | | libffi-based way |
+ | | |
+ | +---------------------------+
+ |
+ |
+ +----------------------------+
+ | Specific language bindings |
+ +----------------------------+
diff --git a/docs/website/buildsystems/autotoolsintegration.rst
b/docs/website/buildsystems/autotoolsintegration.rst
new file mode 100644
index 00000000..6948833b
--- /dev/null
+++ b/docs/website/buildsystems/autotoolsintegration.rst
@@ -0,0 +1,122 @@
+=====================
+Autotools Integration
+=====================
+
+The gobject-introspection package provides the following two macros for use in
+your configure.ac file:
+
+GOBJECT_INTROSPECTION_CHECK([version])
+ This macro adds a ``--enable-introspection=yes|no|auto`` configure
+ option which defaults to ``auto``.
+
+ * ``auto`` - Will set ``HAVE_INTROSPECTION`` if gobject-introspection is available
+ and the version requirement is satisfied.
+ * ``yes`` - Will error out if gobject-introspection is missing or the version
+ requirement is not satisfied. ``HAVE_INTROSPECTION`` will always be true.
+ * ``no`` - Will never error out and ``HAVE_INTROSPECTION`` will always be false.
+
+GOBJECT_INTROSPECTION_REQUIRE([version])
+ This macro does not add a configure option and behaves as if
+ ``--enable-introspection=yes``.
+
+
+Example
+-------
+
+You'll need to adapt this for the library you're adding introspection support
+to.
+
+* configure.ac (or configure.in if no .ac file is used)
+
+ .. code-block:: none
+
+ GOBJECT_INTROSPECTION_CHECK([1.40.0])
+
+* Makefile.am
+
+ .. code-block:: none
+
+ DISTCHECK_CONFIGURE_FLAGS = --enable-introspection
+
+ or just add to the existing DISTCHECK_CONFIGURE_FLAGS
+
+* foo/Makefile.am - must be near the end (after CLEANFILES has been set)
+
+ .. code-block:: none
+
+ -include $(INTROSPECTION_MAKEFILE)
+ INTROSPECTION_GIRS =
+ INTROSPECTION_SCANNER_ARGS = --add-include-path=$(srcdir) --warn-all
+ INTROSPECTION_COMPILER_ARGS = --includedir=$(srcdir)
+
+ if HAVE_INTROSPECTION
+ introspection_sources = $(libfoo_1_0_la_SOURCES)
+
+ Foo-1.0.gir: libfoo-1.0.la
+ Foo_1_0_gir_INCLUDES = GObject-2.0
+ Foo_1_0_gir_CFLAGS = $(INCLUDES)
+ Foo_1_0_gir_LIBS = libfoo-1.0.la
+ Foo_1_0_gir_FILES = $(introspection_sources)
+ INTROSPECTION_GIRS += Foo-1.0.gir
+
+ girdir = $(datadir)/gir-1.0
+ gir_DATA = $(INTROSPECTION_GIRS)
+
+ typelibdir = $(libdir)/girepository-1.0
+ typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
+
+ CLEANFILES += $(gir_DATA) $(typelib_DATA)
+ endif
+
+ You can also check out a complete example at
+ https://gitlab.gnome.org/GNOME/gtk/blob/c0ba041c73214f82d2c32b2ca1fa8f3c388c6170/gtk/Makefile.am#L1571
+
+
+Makefile variable documentation
+-------------------------------
+
+``INTROSPECTION_GIRS`` is the entry point, you should list all the gir files
+you want to build there in the XXX-Y.gir format where X is the name of the gir
+(for example Gtk) and Y is the version (for example 2.0).
+
+If output is Gtk-3.0.gir then you should name the variables like
+``Gtk_3_0_gir_NAMESPACE``, ``Gtk_3_0_gir_VERSION`` etc.
+
+* Required variables:
+
+ * ``FILES`` - C sources and headers which should be scanned
+
+* One of these variables are required:
+
+ * ``LIBS`` - Library where the symbol represented in the gir can be found
+ * ``PROGRAM`` - Program where the symbol represented in the gir can be found
+
+* Optional variables, commonly used:
+
+ * ``INCLUDES`` - Gir files to include without the .gir suffix, for instance
+ GLib-2.0, Gtk-3.0. This is needed for all libraries which you depend on
+ that provides introspection information.
+ * ``SCANNERFLAGS`` - Flags to pass in to the scanner, see g-ir-scanner(1)
+ for a list
+ * ``PACKAGES`` - list of pkg-config names which cflags are required to parse
+ the headers of this gir. Note that ``INCLUDES`` will already fetch the
+ packages and thus the cflags for all dependencies.
+ * ``EXPORT_PACKAGES`` - List of pkg-config names which are provided by this
+ Gir.
+ * ``CFLAGS`` - Flags to pass in to the parser when scanning headers.
+ Normally ``INCLUDES`` and ``PACKAGES`` will fetch the cflags for all
+ dependencies. This is normally used for project specific CFLAGS.
+ * ``LDFLAGS`` - Linker flags used by the scanner. Normally ``INCLUDES`` and
+ ``PACKAGES`` will fetch the ldflags for all dependencies. This is normally
+ used for project-specific LDFLAGS (for instance if you're building several
+ libraries and typelibs).
+
+* Optional variables, seldomly used:
+
+ * ``NAMESPACE`` - Namespace of the gir, first letter capital, rest should be
+ lower case, for instance: 'Gtk', 'Clutter', 'ClutterGtk'. If not present
+ the namespace will be fetched from the gir filename, the part before the
+ first dash. For 'Gtk-3.0', namespace will be 'Gtk'.
+ * ``VERSION`` - Version of the gir, if not present, will be fetched from gir
+ filename, the part after the first dash. For 'Gtk-3.0', version will be
+ '3.0'.
diff --git a/docs/website/buildsystems/index.rst b/docs/website/buildsystems/index.rst
new file mode 100644
index 00000000..c15e592e
--- /dev/null
+++ b/docs/website/buildsystems/index.rst
@@ -0,0 +1,10 @@
+========================
+Build System Integration
+========================
+
+.. toctree::
+ :titlesonly:
+ :maxdepth: 1
+
+ meson
+ autotoolsintegration
diff --git a/docs/website/buildsystems/meson.rst b/docs/website/buildsystems/meson.rst
new file mode 100644
index 00000000..9bb2504a
--- /dev/null
+++ b/docs/website/buildsystems/meson.rst
@@ -0,0 +1,49 @@
+=================
+Meson Integration
+=================
+
+Support for generating GObject introspection data is included in Meson
+directly and accessible through the ``gnome.generate_gir()`` function. See
+the `meson documentation
+<https://mesonbuild.com/Gnome-module.html#gnomegenerate_gir>`__ for details.
+
+For some real examples, see the meson build definitions of various GNOME
+modules:
+
+Pango:
+ https://gitlab.gnome.org/GNOME/pango/blob/master/pango/meson.build
+
+ .. code-block:: python
+
+ pango_gir = gnome.generate_gir(
+ libpango,
+ sources: pango_sources + pango_headers + [ pango_enum_h ],
+ namespace: 'Pango',
+ nsversion: pango_api_version,
+ identifier_prefix: 'Pango',
+ symbol_prefix: 'pango',
+ export_packages: 'pango',
+ includes: [ 'GObject-2.0', 'cairo-1.0', ],
+ header: 'pango/pango.h',
+ install: true,
+ extra_args: gir_args,
+ )
+
+json-glib:
+ https://gitlab.gnome.org/GNOME/json-glib/blob/master/json-glib/meson.build
+
+ .. code-block:: python
+
+ json_glib_gir = gnome.generate_gir(
+ json_lib,
+ sources: source_c + source_h + json_glib_enums + [ json_version_h ],
+ namespace: 'Json',
+ nsversion: json_api_version,
+ identifier_prefix: 'Json',
+ symbol_prefix: 'json',
+ export_packages: json_api_name,
+ includes: [ 'GObject-2.0', 'Gio-2.0', ],
+ header: 'json-glib/json-glib.h',
+ install: true,
+ extra_args: gir_args,
+ )
diff --git a/docs/website/conf.py b/docs/website/conf.py
new file mode 100644
index 00000000..98a51412
--- /dev/null
+++ b/docs/website/conf.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+extensions = [
+ 'sphinx.ext.extlinks',
+]
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build']
+
+html_theme = 'sphinx_rtd_theme'
+html_show_copyright = False
+project = "GObject Introspection"
+html_title = project
+highlight_language = 'c'
+
+html_theme_options = {
+ "display_version": False,
+}
+
+html_static_path = [
+ "extra.css",
+]
+
+html_context = {
+ 'extra_css_files': [
+ '_static/extra.css',
+ ],
+}
+
+extlinks = {
+ 'bzbug': ('https://bugzilla.gnome.org/show_bug.cgi?id=%s', 'bz#'),
+ 'commit': ('https://gitlab.gnome.org/GNOME/gobject-introspection/commit/%s', ''),
+}
diff --git a/docs/website/extra.css b/docs/website/extra.css
new file mode 100644
index 00000000..f8f6de81
--- /dev/null
+++ b/docs/website/extra.css
@@ -0,0 +1,49 @@
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
+ font-family: inherit;
+}
+
+.wy-nav-content a:visited {
+ color: #3091d1;
+}
+
+.wy-side-nav-search {
+ background-color: initial;
+}
+
+.wy-nav-side, .wy-nav-top {
+ background-color: #272525;
+}
+
+.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
+ color: #272525;
+}
+
+.wy-side-nav-search input[type="text"] {
+ border-color: transparent;
+}
+
+.wy-nav-content {
+ margin: initial;
+}
+
+.rst-content div[role=navigation], footer {
+ font-size: 0.85em;
+ color: #999;
+}
+
+.rst-content div[role=navigation] hr {
+ margin-top: 6px;
+}
+
+footer hr {
+ margin-bottom: 6px;
+}
+
+.rst-footer-buttons {
+ display: none;
+}
+
+table td, table th {
+ white-space: normal !important;
+ line-height: 20px;
+}
diff --git a/docs/website/goals.rst b/docs/website/goals.rst
new file mode 100644
index 00000000..a8ebe92e
--- /dev/null
+++ b/docs/website/goals.rst
@@ -0,0 +1,72 @@
+=====
+Goals
+=====
+
+The introspection project has two major goals, and a variety of more minor
+ones.
+
+
+Two level applications - C and <your favorite runtime>
+------------------------------------------------------
+
+It makes sense to build many kinds of applications using (at least) two
+different levels and languages — one for the low level elements, interfacing
+with the OS and/or the hardware; and one for the high level application logic.
+C is good for graphics, multimedia, and lower level systems work. However,
+writing complex software in C is difficult and error-prone. A managed runtime
+such as `JavaScript <https://wiki.gnome.org/JavaScript>`__, Python, Perl,
+Java, Lua, .NET, Scheme etc. makes a lot of sense for non-fast-path
+application logic such as configuration, layout, dialogs, etc.
+
+
+.. note::
+
+ To achieve this goal you need to write your code using GObject convention.
+ For more information about that, see the `GObject tutorial
+ <https://developer.gnome.org/gobject/stable/pt02.html>`__
+
+Thus, one of the major goals of the GObject introspection project is to be a
+convenient bridge between these two worlds, and allow you to choose the right
+tool for the job, rather than being limited inside one or the other. With the
+introspection project, you can write for example a ClutterActor or GtkWidget
+subclass in C, and then without any additional work use that class inside the
+high level language of your choice.
+
+
+Sharing binding infrastructure work, and making the platform even more binding-friendly
+---------------------------------------------------------------------------------------
+
+Historically in GNOME, the core platform has been relatively binding-friendly,
+but there are several details not captured in the C+GObject layer that
+bindings have needed. For example, reference counting semantics and the item
+type inside GList's. Up until now various language bindings such as Python,
+Mono, java-gnome etc. had duplicated copies of hand-maintained metadata, and
+this led to a situation where bindings tended to lag behind until these manual
+fixups were done, or were simply wrong, and your application would crash when
+calling a more obscure function.
+
+The introspection project solves this by putting all of the metadata inside
+the GObject library itself, using annotations in the comments. This will lead
+to less duplicate work from binding authors, and a more reliable experience
+for binding consumers.
+
+Additionally, because the introspection build process will occur inside the
+GObject libraries themselves, a goal is to encourage GObject authors to
+consider shaping their APIs to be more binding friendly from the start, rather
+than as an afterthought.
+
+
+Additional goals and uses
+-------------------------
+
+* API verification - Sometimes the API of a library in our stack changes by
+ accident. Usually by a less experienced developer making a change without
+ realizing it will break applications. Introspecting the available API in
+ each release of the library and comparing it to the last one makes it easy
+ to see what changed
+* Documentation tools - The tools written inside of the GObjectIntrospection
+ can easily be reused to improve that problem. Essentially; replacing
+ gtk-doc. We want to document what we export so it makes sense to glue this
+ together with API verification mentioned above
+* UI Designer infrastructure
+* Serialization/RPC/DBus
diff --git a/docs/website/images/architecture.svg b/docs/website/images/architecture.svg
new file mode 100644
index 00000000..a5011db8
--- /dev/null
+++ b/docs/website/images/architecture.svg
@@ -0,0 +1,120 @@
+<?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="1052.3622" height="744.09448" id="svg2"
version="1.1" inkscape:version="0.48.2 r9819" sodipodi:docname="architecture.svg"
inkscape:export-filename="/home/antono/Documents/Slides/lvee-winter-2012/architecture.png"
inkscape:export-xdpi="303.60001" inkscape:export-ydpi="303.60001">
+ <title id="title3277">GObject Introspection Architecture</title>
+ <defs id="defs4">
+ <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM" style="overflow:visible">
+ <path id="path3833" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5
2.76,0 5,2.24 5,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none"
transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="Arrow2Mend" orient="auto" refY="0" refX="0" id="Arrow2Mend"
style="overflow:visible">
+ <path id="path3795" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609
-1.7354408,5.6174519 -6e-7,8.035443 z" transform="scale(-0.6,-0.6)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend"
style="overflow:visible">
+ <path id="path3789" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609
-1.7354408,5.6174519 -6e-7,8.035443 z" transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="Arrow1Lend" orient="auto" refY="0" refX="0" id="Arrow1Lend"
style="overflow:visible">
+ <path id="path3771" d="M 0,0 5,-5 -12.5,0 5,5 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)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM-3" style="overflow:visible">
+ <path id="path3833-1" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5
2.76,0 5,2.24 5,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none"
transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend-8"
style="overflow:visible">
+ <path id="path3789-9"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352
-2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="matrix(-1.1,0,0,-1.1,-1.1,0)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM-2" style="overflow:visible">
+ <path id="path3833-5" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5
2.76,0 5,2.24 5,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none"
transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/>
+ </marker>
+ <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend-4"
style="overflow:visible">
+ <path id="path3789-0"
style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352
-2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="matrix(-1.1,0,0,-1.1,-1.1,0)" inkscape:connector-curvature="0"/>
+ </marker>
+ </defs>
+ <sodipodi:namedview id="base" pagecolor="#ffffff" bordercolor="#666666" borderopacity="1.0"
inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="0.70710678" inkscape:cx="493.13397"
inkscape:cy="410.25035" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false"
showguides="false" inkscape:guide-bbox="true" inkscape:window-width="1214" inkscape:window-height="776"
inkscape:window-x="66" inkscape:window-y="24" inkscape:window-maximized="1" showborder="true">
+ <sodipodi:guide orientation="0,1" position="535.38085,998.03071" id="guide5157"/>
+ <sodipodi:guide orientation="1,0" position="62.629458,834.386" id="guide5159"/>
+ <sodipodi:guide orientation="1,0" position="692.96465,713.1677" id="guide5161"/>
+ <sodipodi:guide orientation="0,1" position="391.93919,785.89868" id="guide5163"/>
+ <sodipodi:guide orientation="1,0" position="359.61431,833.37585" id="guide5165"/>
+ <sodipodi:guide orientation="1,0" position="394.96965,744.48243" id="guide5167"/>
+ <sodipodi:guide orientation="0,1" position="471.74124,874.7921" id="guide5171"/>
+ <sodipodi:guide orientation="0,1" position="394.96965,684.28572" id="guide5173"/>
+ <sodipodi:guide orientation="0,1" position="333.35034,582.85802" id="guide5179"/>
+ <sodipodi:guide orientation="0,1" position="239.40615,807.11188" id="guide5195"/>
+ <sodipodi:guide orientation="0,1" position="260,444.28571" id="guide5203"/>
+ <sodipodi:guide orientation="0,1" position="274.28571,492.85714" id="guide5207"/>
+ <sodipodi:guide orientation="0,1" position="312.85714,390" id="guide5231"/>
+ <sodipodi:guide orientation="0,1" position="248.57143,251.42857" id="guide5256"/>
+ <sodipodi:guide orientation="1,0" position="201.02036,807.11188" id="guide5277"/>
+ <sodipodi:guide orientation="1,0" position="535.38085,902.06622" id="guide5279"/>
+ <sodipodi:guide orientation="1,0" position="840,492.85714" id="guide5322"/>
+ <sodipodi:guide orientation="0,1" position="1111.4286,647.14286" id="guide5324"/>
+ </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"/>
+ <dc:title>GObject Introspection Architecture</dc:title>
+ <dc:date>2012-02-13</dc:date>
+ <dc:creator>
+ <cc:Agent>
+ <dc:title>Antono Vasiljev</dc:title>
+ </cc:Agent>
+ </dc:creator>
+ <dc:rights>
+ <cc:Agent>
+ <dc:title>http://creativecommons.org/licenses/by-sa/3.0/</dc:title>
+ </cc:Agent>
+ </dc:rights>
+ <dc:language>English</dc:language>
+ <dc:subject>
+ <rdf:Bag>
+ <rdf:li>GObject</rdf:li>
+ <rdf:li>GLib</rdf:li>
+ <rdf:li>GTK</rdf:li>
+ <rdf:li>Bindings</rdf:li>
+ </rdf:Bag>
+ </dc:subject>
+ <dc:publisher>
+ <cc:Agent>
+ <dc:title>http://antono.info/</dc:title>
+ </cc:Agent>
+ </dc:publisher>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g inkscape:label="Tavolo 1" inkscape:groupmode="layer" id="layer1" transform="translate(0,-308.2677)">
+ <rect style="fill:#ffffff;fill-opacity:1;stroke:none" id="rect3211" width="1052" height="743"
x="1.4142075" y="308.36215" rx="0.89988375" ry="1.2800797"/>
+ <rect style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none" id="rect5275" width="254.98872"
height="84.836205" x="176.48564" y="840.18842" rx="2.6552014" ry="2.6552014"/>
+ <rect ry="2.6552014" rx="2.6552014" y="744.00201" x="176.07715" height="56.580166" width="120.5053"
id="rect5268" style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none"/>
+ <rect style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none" id="rect5233" width="120.5053"
height="56.580166" x="310.8797" y="744.00201" rx="2.6552014" ry="2.6552014"/>
+ <rect ry="0.51764756" rx="0.36266771" y="666.01282" x="176.48563" height="56.580166" width="120.09681"
id="rect5149" style="opacity:0.60852715;fill:#8a3673;fill-opacity:1;stroke:none"/>
+ <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect2985" width="225.99976"
height="60.405384" x="176.48564" y="498.12244" rx="0.68247288" ry="0.55264413"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="270.94678" y="531.75018" id="text3759" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan3761" x="270.94678" y="531.75018">foo.c</tspan></text>
+ <path
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"
d="m 232.44911,547.95853 0,130.51524" id="path3763" inkscape:connector-curvature="0"
sodipodi:nodetypes="cc"/>
+ <text sodipodi:linespacing="125%" id="text5151" y="702.40796" x="200.86145"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan y="702.40796" x="200.86145" id="tspan5153"
sodipodi:role="line">libfoo.so</tspan></text>
+ <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect5155" width="120.5053"
height="56.580166" x="310.87967" y="583.90582" rx="0.36390126" ry="0.51764756"/>
+ <path inkscape:connector-curvature="0" id="path5169" d="m 367.66014,547.95853 0,53.10402"
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="343.13705" y="624.99677" id="text5175" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan5177" x="343.13705" y="624.99677">Foo.gir</tspan></text>
+ <rect ry="0.51764756" rx="0.36390126" y="666.01282" x="310.87967" height="56.580166" width="120.5053"
id="rect5181" style="opacity:0.60852715;fill:#8a3673;fill-opacity:1;stroke:none"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="263.1763" y="575.32751" id="text5187" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan5189" x="263.1763" y="575.32751">g-ir-scanner</tspan></text>
+ <text sodipodi:linespacing="125%" id="text5191" y="575.32751" x="196.09328"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan y="575.32751" x="196.09328" id="tspan5193"
sodipodi:role="line">gcc</tspan></text>
+ <path
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"
d="m 367.86439,635.58016 0,37.37708" id="path5197" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/>
+ <text sodipodi:linespacing="125%" id="text5199" y="655.83643" x="256.62698"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan y="655.83643" x="256.62698" id="tspan5201"
sodipodi:role="line">g-ir-compiler</tspan></text>
+ <text sodipodi:linespacing="125%" id="text5209" y="702.40796" x="327.53925"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan y="702.40796" x="327.53925" id="tspan5211"
sodipodi:role="line">Foo.typelib</tspan></text>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="297.02197" y="896.43829" id="text5215" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
x="297.02197" y="896.43829" id="tspan5219"
style="font-size:40px;text-align:center;text-anchor:middle">bindings</tspan></text>
+ <text sodipodi:linespacing="125%" id="text5242" y="777.79724" x="319.70181"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan style="font-size:11.32283497px" y="777.79724" x="319.70181" id="tspan5244"
sodipodi:role="line">libgirrepository.so</tspan></text>
+ <path
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"
d="m 367.66014,753.2557 0,-37.37707" id="path5260" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="201.32657" y="779.81921" id="text5262" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan5264" x="201.32657" y="779.81921" style="font-size:19.41057587px">libffi.so</tspan></text>
+ <path sodipodi:nodetypes="cc" inkscape:connector-curvature="0" id="path5266" d="m 233.0969,749.47378
-0.64779,-30.70879"
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/>
+ <path sodipodi:nodetypes="cc" inkscape:connector-curvature="0" id="path5281" d="m 367.66014,847.01924
0,-55.35074"
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/>
+ <path
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"
d="m 232.44911,845.8143 0,-55.35074" id="path5283" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="490.84418" y="722.04968" id="text5308" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan5310" x="490.84418" y="722.04968"
style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#8a3673;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu
Medium">Deployment</tspan></text>
+ <text sodipodi:linespacing="125%" id="text5318" y="853.72321" x="490.84418"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan
style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#16aa41;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu
Medium" y="853.72321" x="490.84418" id="tspan5320" sodipodi:role="line">Consumption</tspan></text>
+ <text sodipodi:linespacing="125%" id="text5326" y="601.31128" x="490.84418"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#606060;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan
style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#606060;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu
Medium" y="601.31128" x="490.84418" id="tspan5328" sodipodi:role="line">Development</tspan></text>
+ <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect2985-6"
width="254.89937" height="60.405384" x="178.17885" y="404.4209" rx="0.76974374" ry="0.55264413"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="280.45071" y="438.04865" id="text3759-4" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan3761-3" x="280.45071" y="438.04865">foo.vala</tspan></text>
+ <path inkscape:connector-curvature="0" id="path5169-3" d="m 369.35335,454.25697 0,53.10403"
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/>
+ <text xml:space="preserve"
style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="373.75293" y="486.75397" id="text5187-3" sodipodi:linespacing="125%"><tspan sodipodi:role="line"
id="tspan5189-8" x="373.75293" y="486.75397">valac</tspan></text>
+ <path inkscape:connector-curvature="0" id="path5169-3-5" d="m 419.70848,452.574 0,148.40335"
style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/>
+ </g>
+</svg>
\ No newline at end of file
diff --git a/docs/website/images/overview.svg b/docs/website/images/overview.svg
new file mode 100644
index 00000000..f78e5398
--- /dev/null
+++ b/docs/website/images/overview.svg
@@ -0,0 +1,540 @@
+<?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="678.53101"
+ height="468.55246"
+ id="svg2"
+ sodipodi:version="0.32"
+ inkscape:version="0.92.3 (2405546, 2018-03-11)"
+ sodipodi:docname="overview.svg"
+ inkscape:output_extension="org.inkscape.output.svg.inkscape"
+ version="1.1">
+ <defs
+ id="defs4">
+ <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="0.70000001"
+ inkscape:cx="219.00285"
+ inkscape:cy="259.78855"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="840"
+ inkscape:window-height="431"
+ inkscape:window-x="535"
+ inkscape:window-y="227"
+ fit-margin-top="10"
+ fit-margin-left="10"
+ fit-margin-right="10"
+ fit-margin-bottom="10"
+ inkscape:window-maximized="0" />
+ <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"; />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-32.877341,-31.452583)">
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#303030;stroke-width:1.02008247;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.08032983,
1.02008246;stroke-dashoffset:0;stroke-opacity:0.77586209"
+ d="M 42.877341,295.93361 H 701.40837"
+ id="path3171"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <rect
+ style="fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:1.06179869;stroke-opacity:0.62780265"
+ id="rect3185"
+ width="186.36678"
+ height="33.509632"
+ x="67.173752"
+ y="224.53593"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ ry="16.754816" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="76.428574"
+ y="245.93361"
+ id="text3187"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3189"
+ x="76.428574"
+ y="245.93361"
+ style="font-size:16px;line-height:1.25">Introspected GType's</tspan></text>
+ <g
+ id="g3325"
+ transform="translate(-66.428571,30.714286)"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <rect
+ y="102.00188"
+ x="170.53255"
+ height="33.577782"
+ width="109.29207"
+ id="rect3221"
+
style="fill:#739ecd;fill-opacity:1;stroke:#000000;stroke-width:0.99400002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.62780265"
+ ry="16.071428"
+ rx="16.071428" />
+ <text
+ id="text3223"
+ y="124.61499"
+ x="185.23328"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ y="124.61499"
+ x="185.23328"
+ id="tspan3225"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">Sources .c</tspan></text>
+ </g>
+ <g
+ id="g3320"
+ transform="translate(-66.428571,30.714286)"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <rect
+ y="145.21617"
+ x="170.71114"
+ height="33.577782"
+ width="109.29207"
+ id="rect3183"
+ style="fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:0.99365026;stroke-opacity:0.62780265"
+ ry="16.788891" />
+ <text
+ id="text3227"
+ y="167.96991"
+ x="181.77515"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ y="167.96991"
+ x="181.77515"
+ id="tspan3229"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">Headers .h</tspan></text>
+ </g>
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.6243791px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 214.0979,149.31722 74.66135,42.51851"
+ id="path3231"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.48916915px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 254.74458,239.76045 34.08226,-46.93939"
+ id="path3235"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <rect
+ style="fill:#8bc254;fill-opacity:1;stroke:#000000;stroke-width:1.30141628;stroke-opacity:1"
+ id="rect3247"
+ width="208.27"
+ height="135.41287"
+ x="289.4364"
+ y="133.9415"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ ry="18.571428" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="295.99329"
+ y="156.75784"
+ id="text3249"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="156.75784"
+ id="tspan3469"
+ style="font-size:16px;line-height:1.25">GIR - XML format with</tspan><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="176.75784"
+ id="tspan3495"
+ style="font-size:16px;line-height:1.25">introspectable metadata</tspan><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="196.75784"
+ id="tspan3471"
+ style="font-size:16px;line-height:1.25">a language binding need</tspan><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="216.75784"
+ id="tspan3491"
+ style="font-size:16px;line-height:1.25">function,class,enum,</tspan><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="236.75784"
+ id="tspan3515"
+ style="font-size:16px;line-height:1.25">docstrings, struct fields</tspan><tspan
+ sodipodi:role="line"
+ x="295.99329"
+ y="256.75784"
+ id="tspan2561"
+ style="font-size:16px;line-height:1.25">etc</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="227.14287"
+ y="107.36218"
+ id="text3253"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3255"
+ x="227.14287"
+ y="107.36218"
+ style="font-size:16px;line-height:1.25">g-ir-scanner(1)</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="541.42859"
+ y="107.36218"
+ id="text3257"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3259"
+ x="541.42859"
+ y="107.36218"
+ style="font-size:16px;line-height:1.25">g-ir-compiler(1)</tspan></text>
+ <path
+
style="fill:none;fill-opacity:0.35426007;fill-rule:evenodd;stroke:#000000;stroke-width:1.28129315;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:3.84387917,
3.84387917;stroke-dashoffset:0;stroke-opacity:0.48878922"
+ d="M 513.92858,92.402021 V 282.32233"
+ id="path3265"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 212.85714,193.79075 h 75"
+ id="path3279"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.68055099px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 499.4176,193.07647 h 34.73622"
+ id="path3281"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <g
+ id="g3473"
+ transform="translate(24.285714,13.571429)"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <rect
+ y="130.21986"
+ x="510.00055"
+ height="105.71322"
+ width="157.85606"
+ id="rect3277"
+ style="fill:#d0c77b;fill-opacity:1;stroke:#000000;stroke-width:1.00107861;stroke-opacity:1"
+ ry="15.714286" />
+ <text
+ id="text3283"
+ y="153.20482"
+ x="526.4989"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ y="153.20482"
+ x="526.4989"
+ id="tspan3285"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">Typelib - binary</tspan><tspan
+ id="tspan3457"
+ y="173.20482"
+ x="526.4989"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">format for fast</tspan><tspan
+ id="tspan3459"
+ y="193.20482"
+ x="526.4989"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">disk-access and</tspan><tspan
+ id="tspan3461"
+ y="213.20482"
+ x="526.4989"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">low memory</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="44.285713"
+ y="56.647896"
+ id="text3297"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3299"
+ x="44.285713"
+ y="56.647896"
+ style="font-weight:bold;font-size:20px;line-height:1.25;-inkscape-font-specification:'Bitstream
Vera Sans Bold'">Build time</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="48.293804"
+ y="329.10397"
+ id="text3301"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ x="48.293804"
+ y="329.10397"
+ style="font-weight:bold;font-size:20px;line-height:1.25;-inkscape-font-specification:'Bitstream
Vera Sans Bold'"
+ id="tspan3305">Runtime</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="244.28571"
+ y="118.79075"
+ id="text3312"><tspan
+ sodipodi:role="line"
+ id="tspan3314"
+ x="244.28571"
+ y="118.79075"
+ style="font-size:16px;line-height:1.25"> </tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="244.28571"
+ y="118.79075"
+ id="text3316"><tspan
+ sodipodi:role="line"
+ id="tspan3318"
+ x="244.28571"
+ y="118.79075"
+ style="font-size:16px;line-height:1.25"> </tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';-inkscape-font-specification:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="67.14286"
+ y="350.21933"
+ id="text3342"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3344"
+ x="67.14286"
+ y="350.21933"
+
style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12px;line-height:1.25;font-family:'Bitstream
Vera Serif';-inkscape-font-specification:'Bitstream Vera Serif Italic'">How a language binding uses
introspection</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';-inkscape-font-specification:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="66.887283"
+ y="79.159195"
+ id="text3346"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3348"
+ x="66.887283"
+ y="79.159195"
+
style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12px;line-height:1.25;font-family:'Bitstream
Vera Serif';-inkscape-font-specification:'Bitstream Vera Serif Italic'">How a library enables
introspection</tspan></text>
+ <rect
+ style="fill:#d0c77b;fill-opacity:1;stroke:#000000;stroke-width:1.0904454;stroke-opacity:1"
+ id="rect3359"
+ width="191.33812"
+ height="103.481"
+ x="80.402374"
+ y="385.97882"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ ry="20" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="109.08316"
+ y="422.13339"
+ id="text3361"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3363"
+ x="109.08316"
+ y="422.13339"
+ style="font-size:16px;line-height:1.25">Typelib - mmap()</tspan><tspan
+ sodipodi:role="line"
+ x="109.08316"
+ y="442.13339"
+ id="tspan3395"
+ style="font-size:16px;line-height:1.25">shared between</tspan><tspan
+ sodipodi:role="line"
+ x="109.08316"
+ y="462.13339"
+ id="tspan3397"
+ style="font-size:16px;line-height:1.25">processes</tspan></text>
+ <g
+ id="g3413"
+ transform="translate(-30.714286,3.5714286)"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <rect
+ y="388.51193"
+ x="366.86404"
+ height="43.41486"
+ width="148.41486"
+ id="rect3376"
+
style="fill:#cca66e;fill-opacity:1;stroke:#000000;stroke-width:0.44228357;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922"
+ ry="21.70743" />
+ <text
+ id="text3380"
+ y="414.63342"
+ x="383.2746"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ y="414.63342"
+ x="383.2746"
+ id="tspan3382"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">libgirepository</tspan></text>
+ </g>
+ <g
+ id="g3418"
+ transform="translate(-30,3.5714286)"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <rect
+ y="445.21933"
+ x="367.14288"
+ height="37.142857"
+ width="147.85715"
+ id="rect3384"
+
style="fill:#cca66e;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922"
+ ry="18.571428" />
+ <text
+ id="text3386"
+ y="469.75562"
+ x="423.70425"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ y="469.75562"
+ x="423.70425"
+ id="tspan3388"
+ sodipodi:role="line"
+ style="font-size:16px;line-height:1.25">libffi</tspan></text>
+ </g>
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.82769597px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 272.05671,437.35287 63.02944,-25.07684"
+ id="path3399"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.83396173px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 271.62195,443.79905 64.88964,25.78901"
+ id="path3401"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <rect
+
style="opacity:0.98000004;fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:0.88915378;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922"
+ id="rect3403"
+ width="152.96799"
+ height="41.539417"
+ x="529.23022"
+ y="418.02109"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ ry="20.769709" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera
Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ x="537.24548"
+ y="443.20486"
+ id="text3405"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan3407"
+ x="537.24548"
+ y="443.20486"
+ style="font-size:16px;line-height:1.25">dlopen:ed library</tspan></text>
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.21470141px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 484.39306,412.46952 44.78531,25.4996"
+ id="path3409"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ <path
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.19193971px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="M 485.09597,466.55192 529.18975,440.3153"
+ id="path3411"
+
inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:connector-curvature="0" />
+ </g>
+</svg>
diff --git a/docs/website/index.rst b/docs/website/index.rst
new file mode 100644
index 00000000..9b46fe5d
--- /dev/null
+++ b/docs/website/index.rst
@@ -0,0 +1,71 @@
+=====================
+GObject Introspection
+=====================
+
+.. title:: Overview
+
+.. toctree::
+ :hidden:
+ :titlesonly:
+ :maxdepth: 1
+
+ goals
+ architecture
+ users
+ writingbindableapis
+ buildsystems/index
+ annotations/index
+ writingbindings/index
+ tools/index
+
+GObject introspection is a middleware layer between C libraries (using
+GObject) and language bindings. The C library can be scanned at compile time
+and generate metadata files, in addition to the actual native C library. Then
+language bindings can read this metadata and automatically provide bindings to
+call into the C library.
+
+.. figure:: images/overview.svg
+ :width: 85%
+ :align: center
+
+The GI project consists of:
+
+* an XML format called GIR containing introspection information in a machine parseable format
+* a Python package to create and parse the GIR format
+* a scanner to generate GIR format from C source and headers
+* a typelib similar to xpcom/msole which stores the information on disk in a binary format
+* a compiler to compile the typelib from a xml format (and vice versa)
+* C library to read the typelib, :doc:`writingbindings/libgirepository`.
+
+
+Getting the code
+----------------
+
+The latest stable release is available from
+https://download.gnome.org/sources/gobject-introspection
+
+GObject Introspection is stored in git and can be fetched:
+
+.. code-block:: text
+
+ git clone https://gitlab.gnome.org/GNOME/gobject-introspection.git
+
+You can browse the repository online `here <https://gitlab.gnome.org/GNOME/gobject-introspection/>`__.
+
+
+Reporting bugs
+--------------
+
+For a list of existing bugs and feature requests, see the `issues page
+<https://gitlab.gnome.org/GNOME/gobject-introspection/issues>`__. You can also
+`open an issue
+<https://gitlab.gnome.org/GNOME/gobject-introspection/issues/new>`__.
+
+
+Contact
+-------
+
+For questions or additional information, please use:
+
+* Mailing list: gtk-devel-list gnome org
+* IRC: #introspection on irc.gnome.org
diff --git a/docs/website/tools/Makefile b/docs/website/tools/Makefile
new file mode 100644
index 00000000..6fb8baff
--- /dev/null
+++ b/docs/website/tools/Makefile
@@ -0,0 +1,11 @@
+# update man pages
+
+all: ../../g-ir-compiler.1 ../../g-ir-generate.1 ../../g-ir-scanner.1
+
+../../%.1:%.rst
+ rst2man $< > $@
+
+.PHONY: clean
+
+clean:
+ rm -f ../../g-ir-compiler.1 ../../g-ir-generate.1 ../../g-ir-scanner.1
diff --git a/docs/website/tools/g-ir-compiler.rst b/docs/website/tools/g-ir-compiler.rst
new file mode 100644
index 00000000..e87a9abd
--- /dev/null
+++ b/docs/website/tools/g-ir-compiler.rst
@@ -0,0 +1,68 @@
+=============
+g-ir-compiler
+=============
+
+----------------
+Typelib compiler
+----------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**g-ir-compiler** [OPTION...] GIRFILE
+
+
+DESCRIPTION
+===========
+
+g-ir-compiler converts one or more GIR files into one or more typelib. The
+output will be written to standard output unless the ``--output`` is
+specified.
+
+
+OPTIONS
+=======
+
+--help
+ Show help options
+
+--output=FILENAME
+ Save the resulting output in FILENAME.
+
+--verbose
+ Show verbose messages
+
+--debug
+ Show debug messages
+
+--includedir=DIRECTORY
+ Adds a directory which will be used to find includes inside the GIR format.
+
+--module=MODULE
+ FIXME
+
+--shared-library=FILENAME
+ Specifies the shared library where the symbols in the typelib can be
+ found. The name of the library should not contain the ending shared
+ library suffix.
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+http://live.gnome.org/GObjectIntrospection
+
+
+AUTHORS
+=======
+
+Mattias Clasen
diff --git a/docs/website/tools/g-ir-generate.rst b/docs/website/tools/g-ir-generate.rst
new file mode 100644
index 00000000..662ec10b
--- /dev/null
+++ b/docs/website/tools/g-ir-generate.rst
@@ -0,0 +1,54 @@
+=============
+g-ir-generate
+=============
+
+-----------------
+Typelib generator
+-----------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**g-ir-generate** [OPTION...] FILES...
+
+
+DESCRIPTION
+===========
+
+g-ir-generate is an GIR generator, using the repository API. It generates GIR
+files from a raw typelib or in a shared library (``--shlib``). The output will
+be written to standard output unless the ``--output`` is specified.
+
+
+OPTIONS
+=======
+
+--help
+ Show help options
+
+--shlib=FILENAME
+ The shared library to read the symbols from.
+
+--output=FILENAME
+ Save the resulting output in FILENAME.
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+http://live.gnome.org/GObjectIntrospection
+
+
+AUTHORS
+=======
+
+Mattias Clasen
diff --git a/docs/website/tools/g-ir-scanner.rst b/docs/website/tools/g-ir-scanner.rst
new file mode 100644
index 00000000..d59e7ccc
--- /dev/null
+++ b/docs/website/tools/g-ir-scanner.rst
@@ -0,0 +1,171 @@
+============
+g-ir-scanner
+============
+
+----------------------------------------------
+Extracting C metadata from sources and headers
+----------------------------------------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**g-ir-scanner** [OPTION...] FILES...
+
+
+DESCRIPTION
+===========
+
+g-ir-scanner is a tool which generates GIR XML files by parsing headers and
+introspecting GObject based libraries. It is usually invoked during the normal
+build step for a project and the information is saved to disk and later
+installed, so that language bindings and other applications can use it. Header
+files and source files are passed in as arguments on the command line. The
+suffix determines whether a file be treated as a source file (.c) or a header
+file (.h). Currently only C based libraries are supported by the scanner.
+
+
+OPTIONS
+=======
+
+--help
+ Show help options
+
+--quiet
+ If passed, do not print details of normal operation.
+
+--warn-all
+ Display warnings for public API which is not introspectable.
+
+--warn-error
+ Make warnings be fatal errors.
+
+--format=FORMAT
+ This parameters decides which the resulting format will be used. The
+ default value is gir.
+
+--include=NAME
+ Add the specified introspection dependency to the scanned namespace.
+ NAME is of the form NAMESPACE-VERSION, like Gtk-3.0.
+
+--include-uninstalled=PATH
+ Add the specified introspection dependency to the scanned namespace.
+ This differs from ``--include`` in that it takes a file path, and does not
+ process the pkg-config dependencies (since they may not be installed yet).
+
+--add-include-path=PATH
+ Add a directory to the path which the scanner uses to find GIR files. Can
+ be used multiple times to specify multiple directories
+
+-i, --library=LIBRARY
+ Specifies a library that will be introspected. This means that the
+ \*_get_type() functions in it will be called for GObject data types. The
+ name of the library should not contain the leading lib prefix nor the
+ ending shared library suffix.
+
+-L, --library-path=PATH
+ Include this directory when searching for a library. This option can be
+ specified multiple times to include more than one directory to look for
+ libraries in.
+
+-Idirectory
+ Include this directory in the list of directories to be searched for
+ header files. You need to pass to the scanner all the directories you'd
+ normally pass to the compiler when using the specified source files.
+
+-n, --namespace=NAME
+ The namespace name. This name should be capitalized, eg the first letter
+ should be upper case. Examples: Gtk, Clutter, WebKit.
+
+--no-libtool
+ Disable usage of libtool for compiling stub introspection binary. Use this
+ if your build system does not require libtool.
+
+--libtool
+ Full path to libtool executable. Typically used for Automake systems.
+
+--nsversion=VERSION
+ The namespace version. For instance 1.0. This is usually the platform
+ version, eg 2.0 for Gtk+, not 2.12.7.
+
+-p, --program=PROGRAM
+ Specifies a binary that will be introspected. This means that the
+ \*_get_type() functions in it will be called for GObject data types. The
+ binary must be modified to take a ``--introspect-dump=`` option, and to pass
+ the argument to this function to g_irepository_dump.
+
+--program-arg=ARG
+ Additional argument to pass to program for introspection.
+
+--identifier-prefix=PREFIX
+ This option may be specified multiple times. Each one gives a prefix that
+ will be stripped from all C identifiers. If none specified, the namespace
+ will be used. Eg, an identifier prefix of Foo will export the identifier
+ typdef struct _FooBar FooBar; as Foo.Bar.
+
+--symbol-prefix=PREFIX
+ This option may be specified multiple times. Each one gives a
+ prefix that will be stripped from all C symbols. Eg, an symbol
+ prefix of foo will export the symbol foo_bar_do_something as
+ Foo.Bar.do_something.
+
+--accept-unprefixed
+ If specified, the scanner will accept identifiers and symbols which do not
+ match the namespace prefix. Try to avoid using this if possible.
+
+--output=FILENAME
+ Name of the file to output. Normally namespace + format extension. Eg,
+ GLib-2.0.gir.
+
+--pkg=PACKAGE
+ List of pkg-config packages to get compiler and linker flags from. This
+ option can be specified multiple times to include flags from several
+ pkg-config packages.
+
+--pkg-export=PACKAGE
+ List of pkg-config packages that are provided by the generated gir. This
+ option can be specified multiple times if the gir provides more packages.
+ If not specified, the packages specified with ``--pkg=`` will be used.
+
+--verbose
+ Be verbose, include some debugging information.
+
+
+ENVIRONMENT VARIABLES
+=====================
+
+The g-ir-scanner uses the ``XDG_DATA_DIRS`` variable to check for dirs, the
+girs are located in ``XDG_DATA_DIRS/gir-1.0``. It is normally set on a
+distribution so you shouldn't need to set it yourself.
+
+The variable ``GI_SCANNER_DISABLE_CACHE`` ensures that the scanner will not
+write cache data to ``$HOME``.
+
+The variable ``GI_SCANNER_DEBUG`` can be used to debug issues in the
+build-system that involve g-ir-scanner. When it is set to ``save-temps``, then
+g-ir-scanner will not remove temporary files and directories after it
+terminates.
+
+The variable ``GI_HOST_OS`` can be used to control the OS name on the host
+that runs the scanner. It has the same semantics as the Python ``os.name``
+property.
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+http://live.gnome.org/GObjectIntrospection
+
+
+AUTHORS
+=======
+
+Johan Dahlin
diff --git a/docs/website/tools/index.rst b/docs/website/tools/index.rst
new file mode 100644
index 00000000..44897b6c
--- /dev/null
+++ b/docs/website/tools/index.rst
@@ -0,0 +1,21 @@
+==================
+Command Line Tools
+==================
+
+.. toctree::
+ :hidden:
+ :titlesonly:
+ :maxdepth: 1
+
+ g-ir-compiler
+ g-ir-generate
+ g-ir-scanner
+
+:doc:`g-ir-compiler`
+ Typelib compiler
+
+:doc:`g-ir-generate`
+ Typelib generator
+
+:doc:`g-ir-scanner`
+ Extracting C metadata from sources and headers
diff --git a/docs/website/users.rst b/docs/website/users.rst
new file mode 100644
index 00000000..ca7c133d
--- /dev/null
+++ b/docs/website/users.rst
@@ -0,0 +1,52 @@
+=====
+Users
+=====
+
+Bindings based on GObject-Introspection
+---------------------------------------
+
+* `Vala <https://wiki.gnome.org/Projects/Vala>`__ - Compiler for the GObject type system (compile time)
+* `Genie <https://wiki.gnome.org/Projects/Genie>`__ - Genie Language (compile time)
+* `PyGObject <https://wiki.gnome.org/Projects/PyGObject>`__ - Python bindings (runtime)
+* `pygir-ctypes <http://code.google.com/p/pygir-ctypes/>`__ - Pure Python GObject Introspection Repository
(GIR) wrapper using ctypes (runtime)
+* `pgi <http://github.com/lazka/pgi>`__ - Pure Python GObject Introspection Bindings (runtime)
+* `GTK2-Perl/Introspection <https://wiki.gnome.org/GTK2-Perl/Introspection>`__ - Perl bindings (runtime)
+* `JGIR <https://wiki.gnome.org/Projects/JGIR>`__ - Java/JVM bindings (compile time, using typelib)
+* `GJS <https://wiki.gnome.org/Projects/Gjs>`__ - Javascript (spidermonkey) bindings (runtime)
+* `Seed <https://wiki.gnome.org/Projects/Seed>`__ - Javascript (JSCore, WebKit JS engine) bindings (runtime)
+* `sbank <http://live.gnome.org/sbank>`__ - Scheme binding for gobject-introspection (runtime)
+* `GObjectIntrospection/GObjectConsume
<https://wiki.gnome.org/Projects/GObjectIntrospection/GObjectConsume>`__ - Qt bindings (compile time)
+* `GirFFI <http://wiki.github.com/mvz/ruby-gir-ffi>`__ - Ruby bindings (runtime)
+* `lgob <http://oproj.tuxfamily.org/wiki/doku.php?id=lgob>`__ - Lua bindings (compile time?)
+* `guile-gir <http://gitorious.org/guile-gir>`__ - Guile bindings (runtime)
+* `factor-gir <http://github.com/ex-rzr/factor-gir>`__ - Factor bindings (runtime)
+* `lgi <http://www.github.com/pavouk/lgi>`__ - Lua bindings (runtime)
+* `GObject for PHP <https://github.com/megous/gobject-for-php>`__
+* `cl-gir <http://bazaar.launchpad.net/~scymtym/+junk/cl-gir/files>`__ GIR for Common Lisp (work in progress)
+* `GNU Smalltalk <http://www.gitorious.org/gst-gobject-introspection>`__ - A branch of GNU Smalltalk which
adds GObject Introspection bindings.
+* `node-gir <https://github.com/creationix/node-gir>`__ - Node.js bindings to the girepository
+* `go-gir-generator <https://github.com/linuxdeepin/go-gir-generator>`__ - Go bindings (compile time)
(Forked from `gogobject <https://github.com/nsf/gogobject/>`__ which is unmaintained)
+* `haskell-gi <http://www.haskell.org/haskellwiki/GObjectIntrospection>`__ - a Haskell binding for the
GIRepository C library, and a Haskell code generator built upon it. It is very much a work in progress.
+* `cl-gobject-introspection <https://github.com/andy128k/cl-gobject-introspection>`__ - A bridge between
Common Lisp and GObject.
+* `ocaml-gir <http://git.ocamlcore.org/cgi-bin/gitweb.cgi?p=ocaml-gir/ocaml-gir.git>`__ - An automatic
binding generator for gtk-related libraries
+* `gir2pascal <http://wiki.freepascal.org/gir2pascal>`__ - gir2pascal is a program to convert gir files into
into pascal files
+* `PLGI <https://github.com/keriharris/plgi>`__ - Prolog bindings (runtime)
+* `hbgi <https://github.com/tuffnatty/hbgi>`__ - Harbour bindings for GObject Introspection (runtime)
+
+Projects using GObject Introspection
+------------------------------------
+
+ * `Folks <http://telepathy.freedesktop.org/wiki/Folks>`__ - the Gnome contact aggregator
+ * `GnomeShell <https://wiki.gnome.org/Projects/GnomeShell>`__ - prototyping the future gnome shell
+ * `Midgard2 <http://www.midgard2.org/>`__ - language bindings to the Midgard content repository
+ * `libpeas <http://git.gnome.org/browse/libpeas/tree/>`__ - library providing a generic plugin framework
+ * `telepathy-glib <http://telepathy.freedesktop.org/wiki/Telepathy%20GLib>`__ - GLib bindings for Telepathy
+ * `gir2xmi <https://github.com/jralls/gir2xmi>`__ - UML model generator for GObject-Introspection Gir
files.
+ * `playerctl <https://github.com/acrisci/playerctl>`__ - a library and cli for controlling media players
that implement the MPRIS DBus interface
+ * `i3ipc-glib <https://github.com/acrisci/i3ipc-glib>`__ - a library for extensions to the i3 window manager
+
+Projects that could use GObject-Introspection
+---------------------------------------------
+
+ * `Mono GAPI <http://www.mono-project.com/GAPI>`__ could replace its gapi2-parser by using
GOject-Introspection.
+ * `gtkmm <http://www.gtkmm.org/>`__ could use GObject-Introspection in its `gmmproc
<http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/chapter-wrapping-c-libraries.html>`__ to generate C++
library bindings
diff --git a/docs/website/writingbindableapis.rst b/docs/website/writingbindableapis.rst
new file mode 100644
index 00000000..9ab11b47
--- /dev/null
+++ b/docs/website/writingbindableapis.rst
@@ -0,0 +1,163 @@
+=====================
+Writing Bindable APIs
+=====================
+
+Things to avoid
+---------------
+
+Structures with custom memory management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Avoid creating C structures with custom memory management unless they are
+registered as a `boxed type
+<https://developer.gnome.org/gobject/unstable/gobject-Boxed-Types.html>`__.
+If you don't register them as a boxed type bindings will fall back to
+simple memory copying, which might not be what you want.
+
+Also consider using a full `GObject
+<https://developer.gnome.org/gobject/unstable/gobject-The-Base-Object-Type.html>`__
+as that allows bindings to better integrate those objects with the binding
+language, like for example preserve user defined state across language
+boundaries.
+
+Example to avoid:
+
+.. code-block:: c
+
+ struct _GstMiniObject {
+ GTypeInstance instance;
+ /*< public >*/ /* with COW */
+ gint refcount;
+ guint flags;
+
+
+Functionality only accessible through a C macro
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The scanner does not support C macros as API. Solution - add a function
+accessor rather than a macro. This also has the side effect of making
+debugging in C code easier.
+
+Example:
+
+.. code-block:: c
+
+ #define GTK_WIDGET_FLAGS(wid) (GTK_OBJECT_FLAGS (wid))
+
+ GtkWidgetFlags gtk_widget_get_flags (GtkWidget *widget); /* Actually, see
http://bugzilla.gnome.org/show_bug.cgi?id=69872 */
+
+
+Direct C structure access for objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Having GObjects also have fields can be difficult to bind. Create accessor
+functions.
+
+Example:
+
+.. code-block:: c
+
+ struct _SoupMessage {
+ GObject parent;
+
+ /*< public >*/
+ const char *method;
+
+ guint status_code;
+ ...
+ }
+
+ const char * soup_message_get_method (SoupMessage *message); /* Or use a GObject property */
+
+
+va_list
+~~~~~~~
+
+Using varargs can be convenient for C, but they are difficult to bind.
+Solution: Keep the C function for the convenience of C programmers, but add an
+another function which takes an array (either zero terminated or with a length
+parameter).
+
+**Good** example:
+
+.. code-block:: c
+
+ GtkListStore *gtk_list_store_new (gint n_columns,
+ ...);
+ GtkListStore *gtk_list_store_newv (gint n_columns,
+ GType *types);
+
+You can also expose the array variant under the name of the varargs variant
+using the ``rename-to`` annotation:
+``gtk_list_store_newv: (rename-to gtk_list_store_new)``
+
+
+Multiple out parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Multiple out parameters are supported by introspection, but not all languages
+have an obvious mapping for multiple out values. A boxed structure could serve
+as an alternative.
+
+Example to think about (here, there could be a boxed ``struct GtkCoordinate {
+gint x; gint y; }`` structure).
+
+.. code-block:: c
+
+ void gtk_widget_get_pointer (GtkWidget *widget,
+ gint *x,
+ gint *y);
+
+
+Arrays
+~~~~~~
+
+For reference types, zero-terminated arrays are the easiest to work with.
+Arrays of primitive type such as "int" will require length metadata.
+
+
+Callbacks
+~~~~~~~~~
+
+Callbacks are hard to support for introspection bindings because of their
+complex life-cycle. Try to avoid having more than one callback in the same
+function, and consider using GClosure when you need more.
+
+
+Using a different name for error domain quarks from the enum name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Error domain quarks should always be named in the form
+<namespace>_<module>_error_quark() for an error enum called
+<Namespace><Module>Error. Example to avoid:
+
+.. code-block:: c
+
+ typedef enum FooBarError {
+ FOO_BAR_ERROR_MOO,
+ FOO_BAR_ERROR_BLEAT
+ };
+
+ GQuark foo_bar_errors_quark();
+
+
+Custom code in constructors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating an object via ``foo_bar_new()`` shouldn't execute any code
+differently than creating the same object via ``g_object_new()``, since many
+bindings (and also GtkBuilder/Glade) create objects using ``g_object_new()``.
+That is, don't do this:
+
+.. code-block:: c
+
+ FooBar *
+ foo_bar_new (void)
+ {
+ FooBar *retval = FOO_BAR (g_object_new (FOO_TYPE_BAR, NULL));
+ retval->priv->some_variable = 5; /* Don't do this! */
+ return retval;
+ }
+
+Instead, put initialization code in the ``foo_bar_init()`` function or the
+``foo_bar_constructed()`` virtual function.
diff --git a/docs/website/writingbindings/guidelines.rst b/docs/website/writingbindings/guidelines.rst
new file mode 100644
index 00000000..69f1aa78
--- /dev/null
+++ b/docs/website/writingbindings/guidelines.rst
@@ -0,0 +1,45 @@
+==========
+Guidelines
+==========
+
+This page is intended as a guide describing the process of writing a language
+binding for the GObject Introspection framework.
+
+* Decide if you want to make a language binding which is implementation
+ agnostic or implementation specific. Some languages such as Python have
+ libraries which are available across implementations. The Python module
+ ``ctypes`` is a binding for the libffi language binding, which is
+ implemented in a couple of different Python implementations. It's usually
+ easier to target a specific interpreter or compiler implementation so if you
+ unsure, write a specific one.
+
+* For interpreted language implementations, construct the language binding on
+ top of the :doc:`libgirepository` library instead of writing a code generator.
+ It'll make it easier for developers to use your language binding as they
+ will be able to read the typelibs in runtime without having an extra
+ intermediate step to generate the language specific metadata. The
+ libgirepository library can also be used for bindings based upon code
+ generators as an optimization, its a lot faster to read metadata from the
+ typelib than it is to extract the metadata from the GIR XML files.
+
+* Use the Everything library in your unittests, aim at testing all functions
+ there. Do testing as early as possible in the development of the binding, as
+ the code is likely to be more complex than you anticipate.
+
+* Use the same coding style as your language. If libraries for your language
+ normally uses underscores do that as well. For instance, Java bindings
+ should have a method on it's GtkButton wrapper called ``setLabel`` and not
+ ``set_label``.
+
+* If there are existing GObject bindings, reuse them for improved
+ compatibility. It's a nice feature being able to use static bindings and
+ introspected bindings together. The Perl & Python bindings does that.
+
+* Try to stay close to the C language semantics, for instance
+ GObject should be mapped to a class and gtk_button_set_label to a method of
+ that class:
+
+ * java: ``button.setLabel("foo")``
+ * javascript/python/vala: ``button.set_label("foo")``
+ * perl: ``$button->set_label("foo")``
+ * scheme: ``(send button (set-label "foo"))``
diff --git a/docs/website/writingbindings/index.rst b/docs/website/writingbindings/index.rst
new file mode 100644
index 00000000..f1f42a59
--- /dev/null
+++ b/docs/website/writingbindings/index.rst
@@ -0,0 +1,10 @@
+================
+Writing Bindings
+================
+
+.. toctree::
+ :titlesonly:
+ :maxdepth: 1
+
+ guidelines
+ libgirepository
diff --git a/docs/website/writingbindings/libgirepository.rst
b/docs/website/writingbindings/libgirepository.rst
new file mode 100644
index 00000000..9c00e61c
--- /dev/null
+++ b/docs/website/writingbindings/libgirepository.rst
@@ -0,0 +1,15 @@
+===============
+libgirepository
+===============
+
+libgirepository is a C library which provides a C API for accessing the
+typelib data and for interacting with the corresponding GObject based
+libraries.
+
+For more information about libgirepository see the `API documentation
+<https://developer.gnome.org/gi/stable>`__.
+
+The following example shows how to call the ``g_assertion_message()`` function
+from libglib-2.0:
+
+.. literalinclude:: ../../../examples/glib-print.c
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
