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

3 files changed, 70 insertions, 0 deletions

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