[pygobject] docs: document GObject.Object.weak_ref(). Fixes #245

[Christoph Reiter <creiter src gnome org>]

commit 4cd167f0184bbf5991cf7698f88f26881054ae01
Author: Christoph Reiter <reiter christoph gmail com>
Date:   Thu Feb 14 12:35:43 2019 +0100

    docs: document GObject.Object.weak_ref(). Fixes #245

 docs/Makefile               |  2 +-
 docs/guide/api/gobject.rst  |  1 +
 docs/guide/api/weakrefs.rst | 26 ++++++++++++++++++++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)
---
diff --git a/docs/Makefile b/docs/Makefile
index 91dc99c5..55525c52 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -6,7 +6,7 @@ all: _build
 images/%.svg: images/%.dia
        dia $< --export=$@ --filter=dia-svg
 
-_build: Makefile *.rst devguide/*.rst guide/*.rst conf.py images/*.png $(DIA_SVGS) ../README.rst ../NEWS
+_build: Makefile *.rst devguide/*.rst guide/*/*.rst guide/*.rst conf.py images/*.png $(DIA_SVGS) 
../README.rst ../NEWS
        sphinx-build -b html . _build
 
 linkcheck:
diff --git a/docs/guide/api/gobject.rst b/docs/guide/api/gobject.rst
index 08c124b9..63aa0517 100644
--- a/docs/guide/api/gobject.rst
+++ b/docs/guide/api/gobject.rst
@@ -22,6 +22,7 @@ In addition :obj:`GObject.Object` has support for :any:`signals <signals>` and
 
     signals
     properties
+    weakrefs
 
 
 Examples
diff --git a/docs/guide/api/weakrefs.rst b/docs/guide/api/weakrefs.rst
new file mode 100644
index 00000000..6ab9f284
--- /dev/null
+++ b/docs/guide/api/weakrefs.rst
@@ -0,0 +1,26 @@
+Weak References
+===============
+
+While Python has a builtin ``weakref`` module it only allows one to create
+weak references to Python objects, but with PyGObject the Python object
+"wrapping" a GObject and the GObject itself might not have the same lifetime.
+The wrapper can get garbage collected and a new wrapper created again at a
+later point.
+
+If you want to get notified when the underlying GObject gets finalized use
+``GObject.Object.weak_ref``:
+
+
+.. method:: GObject.Object.weak_ref(callback, *user_data)
+
+    Registers a callback to be called when the underlying GObject gets
+    finalized. The callback will receive the give `user_data`.
+
+    To unregister the callback call the ``unref()`` method of the returned
+    GObjectWeakRef object.
+
+    :param callback: A callback which will be called when the object
+        is finalized
+    :type callback: :func:`callable`
+    :param user_data: User data that will be passed to the callback
+    :returns: GObjectWeakRef