From 2dfbadee5da258845aa6192869d0ccc85097aaef Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel@inf.ethz.ch>
Date: Sun, 17 Jan 2016 22:36:37 +0100
Subject: [PATCH] documentation on using multiple extension modules

---
 docs/advanced.rst | 33 +++++++++++++++++++++++++++++++++
 docs/classes.rst  |  2 ++
 2 files changed, 35 insertions(+)

diff --git a/docs/advanced.rst b/docs/advanced.rst
index f8ed303c9..75d4e24f6 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -865,3 +865,36 @@ default argument manually using the ``arg_t`` notation:
     py::class_<MyClass>("MyClass")
         .def("myFunction", py::arg_t<SomeType>("arg", SomeType(123), "SomeType(123)"));
 
+Partitioning code over multiple extension modules
+=================================================
+
+It's straightforward to split binding code over multiple extension modules and
+reference types declared elsewhere. Everything "just" works without any special
+precautions. One exception to this rule occurs when wanting to extend a type declared
+in another extension module. Recall the basic example from Section
+:ref:`inheritance`.
+
+.. code-block:: cpp
+
+    py::class_<Pet> pet(m, "Pet");
+    pet.def(py::init<const std::string &>())
+       .def_readwrite("name", &Pet::name);
+
+    py::class_<Dog>(m, "Dog", pet /* <- specify parent */)
+        .def(py::init<const std::string &>())
+        .def("bark", &Dog::bark);
+
+Suppose now that ``Pet`` bindings are defined in a module named ``basic``,
+whereas the ``Dog`` bindings are defined somewhere else. The challenge is of
+course that the variable ``pet`` is not available anymore though it is needed
+to indicate the inheritance relationship to the constructor of ``class_<Dog>``.
+However, it can be acquired as follows:
+
+.. code-block:: cpp
+
+    py::object pet = (py::object) py::module::import("basic").attr("Pet");
+
+    py::class_<Dog>(m, "Dog", pet)
+        .def(py::init<const std::string &>())
+        .def("bark", &Dog::bark);
+
diff --git a/docs/classes.rst b/docs/classes.rst
index 81621bd93..5aad4d1bf 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -157,6 +157,8 @@ the setter and getter functions:
     and :func:`class_::def_property_readonly_static` are provided for binding
     static variables and properties.
 
+.. _inheritance:
+
 Inheritance
 ===========