ext: Upgrade PyBind11 to version 2.1.1

Change-Id: I16870dec402d661295f9d013dc23e362b2b2c169
Signed-off-by: Andreas Sandberg <andreas.sandberg@arm.com>
Reviewed-by: Curtis Dunham <curtis.dunham@arm.com>
Reviewed-on: https://gem5-review.googlesource.com/3225
Reviewed-by: Jason Lowe-Power <jason@lowepower.com>

22 files changed, 1458 insertions, 386 deletions

diff --git a/ext/pybind11/docs/Doxyfile b/ext/pybind11/docs/Doxyfile
new file mode 100644
index 000000000..4dc8bf059
--- /dev/null
+++ b/ext/pybind11/docs/Doxyfile
@@ -0,0 +1,19 @@
+PROJECT_NAME           = pybind11
+INPUT                  = ../include/pybind11/
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = .build/doxygenxml
+XML_PROGRAMLISTING     = YES
+
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+EXPAND_AS_DEFINED      = PYBIND11_RUNTIME_EXCEPTION
+
+ALIASES                = "rst=\verbatim embed:rst"
+ALIASES               += "endrst=\endverbatim"
+
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
diff --git a/ext/pybind11/docs/advanced/cast/chrono.rst b/ext/pybind11/docs/advanced/cast/chrono.rst
index 6d4a5ee55..8c6b3d7e5 100644
--- a/ext/pybind11/docs/advanced/cast/chrono.rst
+++ b/ext/pybind11/docs/advanced/cast/chrono.rst
@@ -4,8 +4,8 @@ Chrono
 When including the additional header file :file:`pybind11/chrono.h` conversions
 from C++11 chrono datatypes to python datetime objects are automatically enabled.
 This header also enables conversions of python floats (often from sources such
-as `time.monotonic()`, `time.perf_counter()` and `time.process_time()`) into
-durations.
+as ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``)
+into durations.
 
 An overview of clocks in C++11
 ------------------------------
diff --git a/ext/pybind11/docs/advanced/cast/eigen.rst b/ext/pybind11/docs/advanced/cast/eigen.rst
index b83ca9af9..5b0b08ca6 100644
--- a/ext/pybind11/docs/advanced/cast/eigen.rst
+++ b/ext/pybind11/docs/advanced/cast/eigen.rst
@@ -1,48 +1,308 @@
 Eigen
-=====
+#####
 
 `Eigen <http://eigen.tuxfamily.org>`_ is C++ header-based library for dense and
 sparse linear algebra. Due to its popularity and widespread adoption, pybind11
-provides transparent conversion support between Eigen and Scientific Python linear
-algebra data types.
+provides transparent conversion and limited mapping support between Eigen and
+Scientific Python linear algebra data types.
 
-Specifically, when including the optional header file :file:`pybind11/eigen.h`,
-pybind11 will automatically and transparently convert
+To enable the built-in Eigen support you must include the optional header file
+:file:`pybind11/eigen.h`.
 
-1. Static and dynamic Eigen dense vectors and matrices to instances of
-   ``numpy.ndarray`` (and vice versa).
+Pass-by-value
+=============
 
-2. Returned matrix expressions such as blocks (including columns or rows) and
-   diagonals will be converted to ``numpy.ndarray`` of the expression
-   values.
+When binding a function with ordinary Eigen dense object arguments (for
+example, ``Eigen::MatrixXd``), pybind11 will accept any input value that is
+already (or convertible to) a ``numpy.ndarray`` with dimensions compatible with
+the Eigen type, copy its values into a temporary Eigen variable of the
+appropriate type, then call the function with this temporary variable.
 
-3. Returned matrix-like objects such as Eigen::DiagonalMatrix or
-   Eigen::SelfAdjointView will be converted to ``numpy.ndarray`` containing the
-   expressed value.
+Sparse matrices are similarly copied to or from
+``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` objects.
 
-4. Eigen sparse vectors and matrices to instances of
-   ``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` (and vice versa).
+Pass-by-reference
+=================
 
-This makes it possible to bind most kinds of functions that rely on these types.
-One major caveat are functions that take Eigen matrices *by reference* and modify
-them somehow, in which case the information won't be propagated to the caller.
+One major limitation of the above is that every data conversion implicitly
+involves a copy, which can be both expensive (for large matrices) and disallows
+binding functions that change their (Matrix) arguments.  Pybind11 allows you to
+work around this by using Eigen's ``Eigen::Ref<MatrixType>`` class much as you
+would when writing a function taking a generic type in Eigen itself (subject to
+some limitations discussed below).
+
+When calling a bound function accepting a ``Eigen::Ref<const MatrixType>``
+type, pybind11 will attempt to avoid copying by using an ``Eigen::Map`` object
+that maps into the source ``numpy.ndarray`` data: this requires both that the
+data types are the same (e.g. ``dtype='float64'`` and ``MatrixType::Scalar`` is
+``double``); and that the storage is layout compatible.  The latter limitation
+is discussed in detail in the section below, and requires careful
+consideration: by default, numpy matrices and eigen matrices are *not* storage
+compatible.
+
+If the numpy matrix cannot be used as is (either because its types differ, e.g.
+passing an array of integers to an Eigen paramater requiring doubles, or
+because the storage is incompatible), pybind11 makes a temporary copy and
+passes the copy instead.
+
+When a bound function parameter is instead ``Eigen::Ref<MatrixType>`` (note the
+lack of ``const``), pybind11 will only allow the function to be called if it
+can be mapped *and* if the numpy array is writeable (that is
+``a.flags.writeable`` is true).  Any access (including modification) made to
+the passed variable will be transparently carried out directly on the
+``numpy.ndarray``.
+
+This means you can can write code such as the following and have it work as
+expected:
 
 .. code-block:: cpp
 
-    /* The Python bindings of these functions won't replicate
-       the intended effect of modifying the function arguments */
-    void scale_by_2(Eigen::Vector3f &v) {
+    void scale_by_2(Eigen::Ref<Eigen::VectorXd> m) {
         v *= 2;
     }
-    void scale_by_2(Eigen::Ref<Eigen::MatrixXd> &v) {
-        v *= 2;
+
+Note, however, that you will likely run into limitations due to numpy and
+Eigen's difference default storage order for data; see the below section on
+:ref:`storage_orders` for details on how to bind code that won't run into such
+limitations.
+
+.. note::
+
+    Passing by reference is not supported for sparse types.
+
+Returning values to Python
+==========================
+
+When returning an ordinary dense Eigen matrix type to numpy (e.g.
+``Eigen::MatrixXd`` or ``Eigen::RowVectorXf``) pybind11 keeps the matrix and
+returns a numpy array that directly references the Eigen matrix: no copy of the
+data is performed.  The numpy array will have ``array.flags.owndata`` set to
+``False`` to indicate that it does not own the data, and the lifetime of the
+stored Eigen matrix will be tied to the returned ``array``.
+
+If you bind a function with a non-reference, ``const`` return type (e.g.
+``const Eigen::MatrixXd``), the same thing happens except that pybind11 also
+sets the numpy array's ``writeable`` flag to false.
+
+If you return an lvalue reference or pointer, the usual pybind11 rules apply,
+as dictated by the binding function's return value policy (see the
+documentation on :ref:`return_value_policies` for full details).  That means,
+without an explicit return value policy, lvalue references will be copied and
+pointers will be managed by pybind11.  In order to avoid copying, you should
+explictly specify an appropriate return value policy, as in the following
+example:
+
+.. code-block:: cpp
+
+    class MyClass {
+        Eigen::MatrixXd big_mat = Eigen::MatrixXd::Zero(10000, 10000);
+    public:
+        Eigen::MatrixXd &getMatrix() { return big_mat; }
+        const Eigen::MatrixXd &viewMatrix() { return big_mat; }
+    };
+
+    // Later, in binding code:
+    py::class_<MyClass>(m, "MyClass")
+        .def(py::init<>())
+        .def("copy_matrix", &MyClass::getMatrix) // Makes a copy!
+        .def("get_matrix", &MyClass::getMatrix, py::return_value_policy::reference_internal)
+        .def("view_matrix", &MyClass::viewMatrix, py::return_value_policy::reference_internal)
+        ;
+
+.. code-block:: python
+
+    a = MyClass()
+    m = a.get_matrix()   # flags.writeable = True,  flags.owndata = False
+    v = a.view_matrix()  # flags.writeable = False, flags.owndata = False
+    c = a.copy_matrix()  # flags.writeable = True,  flags.owndata = True
+    # m[5,6] and v[5,6] refer to the same element, c[5,6] does not.
+
+Note in this example that ``py::return_value_policy::reference_internal`` is
+used to tie the life of the MyClass object to the life of the returned arrays.
+
+You may also return an ``Eigen::Ref``, ``Eigen::Map`` or other map-like Eigen
+object (for example, the return value of ``matrix.block()`` and related
+methods) that map into a dense Eigen type.  When doing so, the default
+behaviour of pybind11 is to simply reference the returned data: you must take
+care to ensure that this data remains valid!  You may ask pybind11 to
+explicitly *copy* such a return value by using the
+``py::return_value_policy::copy`` policy when binding the function.  You may
+also use ``py::return_value_policy::reference_internal`` or a
+``py::keep_alive`` to ensure the data stays valid as long as the returned numpy
+array does.
+
+When returning such a reference of map, pybind11 additionally respects the
+readonly-status of the returned value, marking the numpy array as non-writeable
+if the reference or map was itself read-only.
+
+.. note::
+
+    Sparse types are always copied when returned.
+
+.. _storage_orders:
+
+Storage orders
+==============
+
+Passing arguments via ``Eigen::Ref`` has some limitations that you must be
+aware of in order to effectively pass matrices by reference.  First and
+foremost is that the default ``Eigen::Ref<MatrixType>`` class requires
+contiguous storage along columns (for column-major types, the default in Eigen)
+or rows if ``MatrixType`` is specifically an ``Eigen::RowMajor`` storage type.
+The former, Eigen's default, is incompatible with ``numpy``'s default row-major
+storage, and so you will not be able to pass numpy arrays to Eigen by reference
+without making one of two changes.
+
+(Note that this does not apply to vectors (or column or row matrices): for such
+types the "row-major" and "column-major" distinction is meaningless).
+
+The first approach is to change the use of ``Eigen::Ref<MatrixType>`` to the
+more general ``Eigen::Ref<MatrixType, 0, Eigen::Stride<Eigen::Dynamic,
+Eigen::Dynamic>>`` (or similar type with a fully dynamic stride type in the
+third template argument).  Since this is a rather cumbersome type, pybind11
+provides a ``py::EigenDRef<MatrixType>`` type alias for your convenience (along
+with EigenDMap for the equivalent Map, and EigenDStride for just the stride
+type).
+
+This type allows Eigen to map into any arbitrary storage order.  This is not
+the default in Eigen for performance reasons: contiguous storage allows
+vectorization that cannot be done when storage is not known to be contiguous at
+compile time.  The default ``Eigen::Ref`` stride type allows non-contiguous
+storage along the outer dimension (that is, the rows of a column-major matrix
+or columns of a row-major matrix), but not along the inner dimension.
+
+This type, however, has the added benefit of also being able to map numpy array
+slices.  For example, the following (contrived) example uses Eigen with a numpy
+slice to multiply by 2 all coefficients that are both on even rows (0, 2, 4,
+...) and in columns 2, 5, or 8:
+
+.. code-block:: cpp
+
+    m.def("scale", [](py::EigenDRef<Eigen::MatrixXd> m, double c) { m *= c; });
+
+.. code-block:: python
+
+    # a = np.array(...)
+    scale_by_2(myarray[0::2, 2:9:3])
+
+The second approach to avoid copying is more intrusive: rearranging the
+underlying data types to not run into the non-contiguous storage problem in the
+first place.  In particular, that means using matrices with ``Eigen::RowMajor``
+storage, where appropriate, such as:
+
+.. code-block:: cpp
+
+    using RowMatrixXd = Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>;
+    // Use RowMatrixXd instead of MatrixXd
+
+Now bound functions accepting ``Eigen::Ref<RowMatrixXd>`` arguments will be
+callable with numpy's (default) arrays without involving a copying.
+
+You can, alternatively, change the storage order that numpy arrays use by
+adding the ``order='F'`` option when creating an array:
+
+.. code-block:: python
+
+    myarray = np.array(source, order='F')
+
+Such an object will be passable to a bound function accepting an
+``Eigen::Ref<MatrixXd>`` (or similar column-major Eigen type).
+
+One major caveat with this approach, however, is that it is not entirely as
+easy as simply flipping all Eigen or numpy usage from one to the other: some
+operations may alter the storage order of a numpy array.  For example, ``a2 =
+array.transpose()`` results in ``a2`` being a view of ``array`` that references
+the same data, but in the opposite storage order!
+
+While this approach allows fully optimized vectorized calculations in Eigen, it
+cannot be used with array slices, unlike the first approach.
+
+When *returning* a matrix to Python (either a regular matrix, a reference via
+``Eigen::Ref<>``, or a map/block into a matrix), no special storage
+consideration is required: the created numpy array will have the required
+stride that allows numpy to properly interpret the array, whatever its storage
+order.
+
+Failing rather than copying
+===========================
+
+The default behaviour when binding ``Eigen::Ref<const MatrixType>`` eigen
+references is to copy matrix values when passed a numpy array that does not
+conform to the element type of ``MatrixType`` or does not have a compatible
+stride layout.  If you want to explicitly avoid copying in such a case, you
+should bind arguments using the ``py::arg().noconvert()`` annotation (as
+described in the :ref:`nonconverting_arguments` documentation).
+
+The following example shows an example of arguments that don't allow data
+copying to take place:
+
+.. code-block:: cpp
+
+    // The method and function to be bound:
+    class MyClass {
+        // ...
+        double some_method(const Eigen::Ref<const MatrixXd> &matrix) { /* ... */ }
+    };
+    float some_function(const Eigen::Ref<const MatrixXf> &big,
+                        const Eigen::Ref<const MatrixXf> &small) {
+        // ...
     }
 
-To see why this is, refer to the section on :ref:`opaque` (although that
-section specifically covers STL data types, the underlying issue is the same).
-The :ref:`numpy` sections discuss an efficient alternative for exposing the
-underlying native Eigen types as opaque objects in a way that still integrates
-with NumPy and SciPy.
+    // The associated binding code:
+    using namespace pybind11::literals; // for "arg"_a
+    py::class_<MyClass>(m, "MyClass")
+        // ... other class definitions
+        .def("some_method", &MyClass::some_method, py::arg().nocopy());
+
+    m.def("some_function", &some_function,
+        "big"_a.nocopy(), // <- Don't allow copying for this arg
+        "small"_a         // <- This one can be copied if needed
+    );
+
+With the above binding code, attempting to call the the ``some_method(m)``
+method on a ``MyClass`` object, or attempting to call ``some_function(m, m2)``
+will raise a ``RuntimeError`` rather than making a temporary copy of the array.
+It will, however, allow the ``m2`` argument to be copied into a temporary if
+necessary.
+
+Note that explicitly specifying ``.noconvert()`` is not required for *mutable*
+Eigen references (e.g. ``Eigen::Ref<MatrixXd>`` without ``const`` on the
+``MatrixXd``): mutable references will never be called with a temporary copy.
+
+Vectors versus column/row matrices
+==================================
+
+Eigen and numpy have fundamentally different notions of a vector.  In Eigen, a
+vector is simply a matrix with the number of columns or rows set to 1 at
+compile time (for a column vector or row vector, respectively).  Numpy, in
+contast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has
+1-dimensional arrays of size N.
+
+When passing a 2-dimensional 1xN or Nx1 array to Eigen, the Eigen type must
+have matching dimensions: That is, you cannot pass a 2-dimensional Nx1 numpy
+array to an Eigen value expecting a row vector, or a 1xN numpy array as a
+column vector argument.
+
+On the other hand, pybind11 allows you to pass 1-dimensional arrays of length N
+as Eigen parameters.  If the Eigen type can hold a column vector of length N it
+will be passed as such a column vector.  If not, but the Eigen type constraints
+will accept a row vector, it will be passed as a row vector.  (The column
+vector takes precendence when both are supported, for example, when passing a
+1D numpy array to a MatrixXd argument).  Note that the type need not be
+expicitly a vector: it is permitted to pass a 1D numpy array of size 5 to an
+Eigen ``Matrix<double, Dynamic, 5>``: you would end up with a 1x5 Eigen matrix.
+Passing the same to an ``Eigen::MatrixXd`` would result in a 5x1 Eigen matrix.
+
+When returning an eigen vector to numpy, the conversion is ambiguous: a row
+vector of length 4 could be returned as either a 1D array of length 4, or as a
+2D array of size 1x4.  When encoutering such a situation, pybind11 compromises
+by considering the returned Eigen type: if it is a compile-time vector--that
+is, the type has either the number of rows or columns set to 1 at compile
+time--pybind11 converts to a 1D numpy array when returning the value.  For
+instances that are a vector only at run-time (e.g. ``MatrixXd``,
+``Matrix<float, Dynamic, 4>``), pybind11 returns the vector as a 2D array to
+numpy.  If this isn't want you want, you can use ``array.reshape(...)`` to get
+a view of the same data in the desired dimensions.
 
 .. seealso::
 
diff --git a/ext/pybind11/docs/advanced/cast/index.rst b/ext/pybind11/docs/advanced/cast/index.rst
index 36586af5c..54c10570b 100644
--- a/ext/pybind11/docs/advanced/cast/index.rst
+++ b/ext/pybind11/docs/advanced/cast/index.rst
@@ -33,6 +33,7 @@ the last case of the above list.
    :maxdepth: 1
 
    overview
+   strings
    stl
    functional
    chrono
diff --git a/ext/pybind11/docs/advanced/cast/overview.rst b/ext/pybind11/docs/advanced/cast/overview.rst
index ab37b90be..54c11a90a 100644
--- a/ext/pybind11/docs/advanced/cast/overview.rst
+++ b/ext/pybind11/docs/advanced/cast/overview.rst
@@ -94,14 +94,26 @@ as arguments and return values, refer to the section on binding :ref:`classes`.
 +------------------------------------+---------------------------+-------------------------------+
 | ``char``                           | Character literal         | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
+| ``char16_t``                       | UTF-16 character literal  | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
+| ``char32_t``                       | UTF-32 character literal  | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
 | ``wchar_t``                        | Wide character literal    | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
 | ``const char *``                   | UTF-8 string literal      | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
+| ``const char16_t *``               | UTF-16 string literal     | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
+| ``const char32_t *``               | UTF-32 string literal     | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
 | ``const wchar_t *``                | Wide string literal       | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
 | ``std::string``                    | STL dynamic UTF-8 string  | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
+| ``std::u16string``                 | STL dynamic UTF-16 string | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
+| ``std::u32string``                 | STL dynamic UTF-32 string | :file:`pybind11/pybind11.h`   |
++------------------------------------+---------------------------+-------------------------------+
 | ``std::wstring``                   | STL dynamic wide string   | :file:`pybind11/pybind11.h`   |
 +------------------------------------+---------------------------+-------------------------------+
 | ``std::pair<T1, T2>``              | Pair of two custom types  | :file:`pybind11/pybind11.h`   |
diff --git a/ext/pybind11/docs/advanced/cast/stl.rst b/ext/pybind11/docs/advanced/cast/stl.rst
index bbd23732b..c76da5ca1 100644
--- a/ext/pybind11/docs/advanced/cast/stl.rst
+++ b/ext/pybind11/docs/advanced/cast/stl.rst
@@ -5,10 +5,12 @@ Automatic conversion
 ====================
 
 When including the additional header file :file:`pybind11/stl.h`, conversions
-between ``std::vector<>``, ``std::list<>``, ``std::set<>``, and ``std::map<>``
-and the Python ``list``, ``set`` and ``dict`` data structures are automatically
-enabled. The types ``std::pair<>`` and ``std::tuple<>`` are already supported
-out of the box with just the core :file:`pybind11/pybind11.h` header.
+between ``std::vector<>``/``std::list<>``/``std::array<>``,
+``std::set<>``/``std::unordered_set<>``, and
+``std::map<>``/``std::unordered_map<>`` and the Python ``list``, ``set`` and
+``dict`` data structures are automatically enabled. The types ``std::pair<>``
+and ``std::tuple<>`` are already supported out of the box with just the core
+:file:`pybind11/pybind11.h` header.
 
 The major downside of these implicit conversions is that containers must be
 converted (i.e. copied) on every Python->C++ and C++->Python transition, which
@@ -72,7 +74,7 @@ functions:
     /* ... binding code ... */
 
     py::class_<MyClass>(m, "MyClass")
-        .def(py::init<>)
+        .def(py::init<>())
         .def_readwrite("contents", &MyClass::contents);
 
 In this case, properties can be read and written in their entirety. However, an
diff --git a/ext/pybind11/docs/advanced/cast/strings.rst b/ext/pybind11/docs/advanced/cast/strings.rst
new file mode 100644
index 000000000..c70fb0bec
--- /dev/null
+++ b/ext/pybind11/docs/advanced/cast/strings.rst
@@ -0,0 +1,243 @@
+Strings, bytes and Unicode conversions
+######################################
+
+.. note::
+
+    This section discusses string handling in terms of Python 3 strings. For Python 2.7, replace all occurrences of ``str`` with ``unicode`` and ``bytes`` with ``str``.  Python 2.7 users may find it best to use ``from __future__ import unicode_literals`` to avoid unintentionally using ``str`` instead of ``unicode``.
+
+Passing Python strings to C++
+=============================
+
+When a Python ``str`` is passed from Python to a C++ function that accepts ``std::string`` or ``char *`` as arguments, pybind11 will encode the Python string to UTF-8. All Python ``str`` can be encoded in UTF-8, so this operation does not fail.
+
+The C++ language is encoding agnostic. It is the responsibility of the programmer to track encodings. It's often easiest to simply `use UTF-8 everywhere <http://utf8everywhere.org/>`_.
+
+.. code-block:: c++
+
+    m.def("utf8_test",
+        [](const std::string &s) {
+            cout << "utf-8 is icing on the cake.\n";
+            cout << s;
+        }
+    );
+    m.def("utf8_charptr",
+        [](const char *s) {
+            cout << "My favorite food is\n";
+            cout << s;
+        }
+    );
+
+.. code-block:: python
+
+    >>> utf8_test('🎂')
+    utf-8 is icing on the cake.
+    🎂
+
+    >>> utf8_charptr('🍕')
+    My favorite food is
+    🍕
+
+.. note::
+
+    Some terminal emulators do not support UTF-8 or emoji fonts and may not display the example above correctly.
+
+The results are the same whether the C++ function accepts arguments by value or reference, and whether or not ``const`` is used.
+
+Passing bytes to C++
+--------------------
+
+A Python ``bytes`` object will be passed to C++ functions that accept ``std::string`` or ``char*`` *without* conversion. 
+
+
+Returning C++ strings to Python
+===============================
+
+When a C++ function returns a ``std::string`` or ``char*`` to a Python caller, **pybind11 will assume that the string is valid UTF-8** and will decode it to a native Python ``str``, using the same API as Python uses to perform ``bytes.decode('utf-8')``. If this implicit conversion fails, pybind11 will raise a ``UnicodeDecodeError``. 
+
+.. code-block:: c++
+
+    m.def("std_string_return",
+        []() {
+            return std::string("This string needs to be UTF-8 encoded");
+        }
+    );
+
+.. code-block:: python
+
+    >>> isinstance(example.std_string_return(), str)
+    True
+
+
+Because UTF-8 is inclusive of pure ASCII, there is never any issue with returning a pure ASCII string to Python. If there is any possibility that the string is not pure ASCII, it is necessary to ensure the encoding is valid UTF-8.
+
+.. warning::
+
+    Implicit conversion assumes that a returned ``char *`` is null-terminated. If there is no null terminator a buffer overrun will occur.
+
+Explicit conversions
+--------------------
+
+If some C++ code constructs a ``std::string`` that is not a UTF-8 string, one can perform a explicit conversion and return a ``py::str`` object. Explicit conversion has the same overhead as implicit conversion.
+
+.. code-block:: c++
+
+    // This uses the Python C API to convert Latin-1 to Unicode
+    m.def("str_output",
+        []() {
+            std::string s = "Send your r\xe9sum\xe9 to Alice in HR"; // Latin-1
+            py::str py_s = PyUnicode_DecodeLatin1(s.data(), s.length());
+            return py_s;
+        }
+    );
+
+.. code-block:: python
+
+    >>> str_output()
+    'Send your résumé to Alice in HR'
+
+The `Python C API <https://docs.python.org/3/c-api/unicode.html#built-in-codecs>`_ provides several built-in codecs.
+
+
+One could also use a third party encoding library such as libiconv to transcode to UTF-8.
+
+Return C++ strings without conversion
+-------------------------------------
+
+If the data in a C++ ``std::string`` does not represent text and should be returned to Python as ``bytes``, then one can return the data as a ``py::bytes`` object.
+
+.. code-block:: c++
+
+    m.def("return_bytes",
+        []() {
+            std::string s("\xba\xd0\xba\xd0");  // Not valid UTF-8
+            return py::bytes(s);  // Return the data without transcoding
+        }
+    );
+
+.. code-block:: python
+
+    >>> example.return_bytes()
+    b'\xba\xd0\xba\xd0'
+
+
+Note the asymmetry: pybind11 will convert ``bytes`` to ``std::string`` without encoding, but cannot convert ``std::string`` back to ``bytes`` implicitly.
+
+.. code-block:: c++
+
+    m.def("asymmetry",
+        [](std::string s) {  // Accepts str or bytes from Python
+            return s;  // Looks harmless, but implicitly converts to str
+        }
+    );    
+
+.. code-block:: python
+
+    >>> isinstance(example.asymmetry(b"have some bytes"), str)
+    True
+
+    >>> example.asymmetry(b"\xba\xd0\xba\xd0")  # invalid utf-8 as bytes
+    UnicodeDecodeError: 'utf-8' codec can't decode byte 0xba in position 0: invalid start byte
+
+
+Wide character strings
+======================
+
+When a Python ``str`` is passed to a C++ function expecting ``std::wstring``, ``wchar_t*``, ``std::u16string`` or ``std::u32string``, the ``str`` will be encoded to UTF-16 or UTF-32 depending on how the C++ compiler implements each type, in the platform's endian. When strings of these types are returned, they are assumed to contain valid UTF-16 or UTF-32, and will be decoded to Python ``str``.
+
+.. code-block:: c++
+
+    #define UNICODE
+    #include <windows.h>
+
+    m.def("set_window_text",
+        [](HWND hwnd, std::wstring s) {
+            // Call SetWindowText with null-terminated UTF-16 string
+            ::SetWindowText(hwnd, s.c_str());
+        }
+    );
+    m.def("get_window_text",
+        [](HWND hwnd) {
+            const int buffer_size = ::GetWindowTextLength(hwnd) + 1;
+            auto buffer = std::make_unique< wchar_t[] >(buffer_size);
+
+            ::GetWindowText(hwnd, buffer.data(), buffer_size);
+
+            std::wstring text(buffer.get());
+
+            // wstring will be converted to Python str
+            return text;
+        }
+    );
+
+.. warning::
+
+    Wide character strings may not work as described on Python 2.7 or Python 3.3 compiled with ``--enable-unicode=ucs2``.
+
+Strings in multibyte encodings such as Shift-JIS must transcoded to a UTF-8/16/32 before being returned to Python.
+
+
+Character literals
+==================
+
+C++ functions that accept character literals as input will receive the first character of a Python ``str`` as their input. If the string is longer than one Unicode character, trailing characters will be ignored.
+
+When a character literal is returned from C++ (such as a ``char`` or a ``wchar_t``), it will be converted to a ``str`` that represents the single character.
+
+.. code-block:: c++
+
+    m.def("pass_char", [](char c) { return c; });
+    m.def("pass_wchar", [](wchar_t w) { return w; });
+
+.. code-block:: python
+    
+    >>> example.pass_char('A')
+    'A'
+
+While C++ will cast integers to character types (``char c = 0x65;``), pybind11 does not convert Python integers to characters implicitly. The Python function ``chr()`` can be used to convert integers to characters.
+
+.. code-block:: python
+    
+    >>> example.pass_char(0x65)
+    TypeError
+
+    >>> example.pass_char(chr(0x65))
+    'A'
+
+If the desire is to work with an 8-bit integer, use ``int8_t`` or ``uint8_t`` as the argument type.
+
+Grapheme clusters
+-----------------
+
+A single grapheme may be represented by two or more Unicode characters. For example 'é' is usually represented as U+00E9 but can also be expressed as the combining character sequence U+0065 U+0301 (that is, the letter 'e' followed by a combining acute accent). The combining character will be lost if the two-character sequence is passed as an argument, even though it renders as a single grapheme.
+
+.. code-block:: python
+
+    >>> example.pass_wchar('é')
+    'é'
+
+    >>> combining_e_acute = 'e' + '\u0301'
+
+    >>> combining_e_acute
+    'é'
+
+    >>> combining_e_acute == 'é'
+    False
+
+    >>> example.pass_wchar(combining_e_acute)
+    'e'
+
+Normalizing combining characters before passing the character literal to C++ may resolve *some* of these issues:
+
+.. code-block:: python
+
+    >>> example.pass_wchar(unicodedata.normalize('NFC', combining_e_acute))
+    'é'
+
+In some languages (Thai for example), there are `graphemes that cannot be expressed as a single Unicode code point <http://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries>`_, so there is no way to capture them in a C++ character type.
+
+
+References
+==========
+
+* `The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) <https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/>`_
+* `C++ - Using STL Strings at Win32 API Boundaries <https://msdn.microsoft.com/en-ca/magazine/mt238407.aspx>`_ 
\ No newline at end of file
diff --git a/ext/pybind11/docs/advanced/classes.rst b/ext/pybind11/docs/advanced/classes.rst
index 4a423b578..8896441b6 100644
--- a/ext/pybind11/docs/advanced/classes.rst
+++ b/ext/pybind11/docs/advanced/classes.rst
@@ -79,7 +79,7 @@ helper class that is defined as follows:
             PYBIND11_OVERLOAD_PURE(
                 std::string, /* Return type */
                 Animal,      /* Parent class */
-                go,          /* Name of function */
+                go,          /* Name of function in C++ (must match Python name) */
                 n_times      /* Argument(s) */
             );
         }
@@ -90,7 +90,8 @@ functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have
 a default implementation.  There are also two alternate macros
 :func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which
 take a string-valued name argument between the *Parent class* and *Name of the
-function* slots. This is useful when the C++ and Python versions of the
+function* slots, which defines the name of function in Python. This is required 
+when the C++ and Python versions of the
 function have different names, e.g.  ``operator()`` vs ``__call__``.
 
 The binding code also needs a few minor adaptations (highlighted):
@@ -115,11 +116,20 @@ The binding code also needs a few minor adaptations (highlighted):
     }
 
 Importantly, pybind11 is made aware of the trampoline helper class by
-specifying it as an extra template argument to :class:`class_`.  (This can also
+specifying it as an extra template argument to :class:`class_`. (This can also
 be combined with other template arguments such as a custom holder type; the
 order of template types does not matter).  Following this, we are able to
 define a constructor as usual.
 
+Bindings should be made against the actual class, not the trampoline helper class.
+
+.. code-block:: cpp
+
+    py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
+        animal
+            .def(py::init<>())
+            .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */
+
 Note, however, that the above is sufficient for allowing python classes to
 extend ``Animal``, but not ``Dog``: see ref:`virtual_and_inheritance` for the
 necessary steps required to providing proper overload support for inherited
@@ -186,7 +196,7 @@ example as follows:
         virtual std::string go(int n_times) = 0;
         virtual std::string name() { return "unknown"; }
     };
-    class Dog : public class Animal {
+    class Dog : public Animal {
     public:
         std::string go(int n_times) override {
             std::string result;
@@ -220,6 +230,13 @@ override the ``name()`` method):
         std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); }
     };
 
+.. note::
+
+    Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()``
+    and ``bark()``. These are needed to portably implement a trampoline for a
+    function that does not take any arguments. For functions that take
+    a nonzero number of arguments, the trailing comma must be omitted.
+
 A registered class derived from a pybind11-registered class with virtual
 methods requires a similar trampoline class, *even if* it doesn't explicitly
 declare or override any virtual methods itself:
@@ -228,7 +245,8 @@ declare or override any virtual methods itself:
 
     class Husky : public Dog {};
     class PyHusky : public Husky {
-        using Dog::Dog; // Inherit constructors
+    public:
+        using Husky::Husky; // Inherit constructors
         std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); }
         std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); }
         std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); }
@@ -242,11 +260,13 @@ follows:
 .. code-block:: cpp
 
     template <class AnimalBase = Animal> class PyAnimal : public AnimalBase {
+    public:
         using AnimalBase::AnimalBase; // Inherit constructors
         std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); }
         std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); }
     };
     template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> {
+    public:
         using PyAnimal<DogBase>::PyAnimal; // Inherit constructors
         // Override PyAnimal's pure virtual go() with a non-pure one:
         std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); }
@@ -373,7 +393,9 @@ crucial that instances are deallocated on the C++ side to avoid memory leaks.
     /* ... binding code ... */
 
     py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass")
-        .def(py::init<>)
+        .def(py::init<>())
+
+.. _implicit_conversions:
 
 Implicit conversions
 ====================
@@ -422,11 +444,11 @@ The section on :ref:`properties` discussed the creation of instance properties
 that are implemented in terms of C++ getters and setters.
 
 Static properties can also be created in a similar way to expose getters and
-setters of static class attributes. It is important to note that the implicit
-``self`` argument also exists in this case and is used to pass the Python
-``type`` subclass instance. This parameter will often not be needed by the C++
-side, and the following example illustrates how to instantiate a lambda getter
-function that ignores it:
+setters of static class attributes. Note that the implicit ``self`` argument
+also exists in this case and is used to pass the Python ``type`` subclass
+instance. This parameter will often not be needed by the C++ side, and the
+following example illustrates how to instantiate a lambda getter function
+that ignores it:
 
 .. code-block:: cpp
 
@@ -478,6 +500,7 @@ to Python.
             .def(py::self += py::self)
             .def(py::self *= float())
             .def(float() * py::self)
+            .def(py::self * float())
             .def("__repr__", &Vector2::toString);
 
         return m.ptr();
diff --git a/ext/pybind11/docs/advanced/functions.rst b/ext/pybind11/docs/advanced/functions.rst
index f291e8222..e0b0fe095 100644
--- a/ext/pybind11/docs/advanced/functions.rst
+++ b/ext/pybind11/docs/advanced/functions.rst
@@ -6,6 +6,8 @@ with the basics of binding functions and classes, as explained in :doc:`/basics`
 and :doc:`/classes`. The following guide is applicable to both free and member
 functions, i.e. *methods* in Python.
 
+.. _return_value_policies:
+
 Return value policies
 =====================
 
@@ -14,7 +16,7 @@ lifetime of objects managed by them. This can lead to issues when creating
 bindings for functions that return a non-trivial type. Just by looking at the
 type information, it is not clear whether Python should take charge of the
 returned value and eventually free its resources, or if this is handled on the
-C++ side. For this reason, pybind11 provides a several `return value policy`
+C++ side. For this reason, pybind11 provides a several *return value policy*
 annotations that can be passed to the :func:`module::def` and
 :func:`class_::def` functions. The default policy is
 :enum:`return_value_policy::automatic`.
@@ -24,11 +26,11 @@ Just to illustrate what can go wrong, consider the following simple example:
 
 .. code-block:: cpp
 
-    /* Function declaration */ 
+    /* Function declaration */
     Data *get_data() { return _data; /* (pointer to a static data structure) */ }
     ...
 
-    /* Binding code */ 
+    /* Binding code */
     m.def("get_data", &get_data); // <-- KABOOM, will cause crash when called from Python
 
 What's going on here? When ``get_data()`` is called from Python, the return
@@ -44,7 +46,7 @@ silent data corruption.
 
 In the above example, the policy :enum:`return_value_policy::reference` should have
 been specified so that the global data instance is only *referenced* without any
-implied transfer of ownership, i.e.: 
+implied transfer of ownership, i.e.:
 
 .. code-block:: cpp
 
@@ -88,11 +90,12 @@ The following table provides an overview of available policies:
 |                                                  | return value is referenced by Python. This is the default policy for       |
 |                                                  | property getters created via ``def_property``, ``def_readwrite``, etc.     |
 +--------------------------------------------------+----------------------------------------------------------------------------+
-| :enum:`return_value_policy::automatic`           | This is the default return value policy, which falls back to the policy    |
+| :enum:`return_value_policy::automatic`           | **Default policy.** This policy falls back to the policy                   |
 |                                                  | :enum:`return_value_policy::take_ownership` when the return value is a     |
-|                                                  | pointer. Otherwise, it uses :enum:`return_value::move` or                  |
-|                                                  | :enum:`return_value::copy` for rvalue and lvalue references, respectively. |
-|                                                  | See above for a description of what all of these different policies do.    |
+|                                                  | pointer. Otherwise, it uses :enum:`return_value_policy::move` or           |
+|                                                  | :enum:`return_value_policy::copy` for rvalue and lvalue references,        |
+|                                                  | respectively. See above for a description of what all of these different   |
+|                                                  | policies do.                                                               |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 | :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the   |
 |                                                  | return value is a pointer. This is the default conversion policy for       |
@@ -158,8 +161,12 @@ targeted arguments can be passed through the :class:`cpp_function` constructor:
 Additional call policies
 ========================
 
-In addition to the above return value policies, further `call policies` can be
-specified to indicate dependencies between parameters. There is currently just
+In addition to the above return value policies, further *call policies* can be
+specified to indicate dependencies between parameters. In general, call policies
+are required when the C++ object is any kind of container and another object is being
+added to the container.
+
+There is currently just
 one policy named ``keep_alive<Nurse, Patient>``, which indicates that the
 argument with index ``Patient`` should be kept alive at least until the
 argument with index ``Nurse`` is freed by the garbage collector. Argument
@@ -207,8 +214,8 @@ For instance, the following statement iterates over a Python ``dict``:
     void print_dict(py::dict dict) {
         /* Easily interact with Python types */
         for (auto item : dict)
-            std::cout << "key=" << item.first << ", "
-                      << "value=" << item.second << std::endl;
+            std::cout << "key=" << std::string(py::str(item.first)) << ", "
+                      << "value=" << std::string(py::str(item.second)) << std::endl;
     }
 
 It can be exported:
@@ -252,16 +259,21 @@ Such functions can also be created using pybind11:
    m.def("generic", &generic);
 
 The class ``py::args`` derives from ``py::tuple`` and ``py::kwargs`` derives
-from ``py::dict``. Note that the ``kwargs`` argument is invalid if no keyword
-arguments were actually provided. Please refer to the other examples for
-details on how to iterate over these, and on how to cast their entries into
-C++ objects. A demonstration is also available in
-``tests/test_kwargs_and_defaults.cpp``.
+from ``py::dict``.
 
-.. warning::
+You may also use just one or the other, and may combine these with other
+arguments as long as the ``py::args`` and ``py::kwargs`` arguments are the last
+arguments accepted by the function.
 
-   Unlike Python, pybind11 does not allow combining normal parameters with the
-   ``args`` / ``kwargs`` special parameters.
+Please refer to the other examples for details on how to iterate over these,
+and on how to cast their entries into C++ objects. A demonstration is also
+available in ``tests/test_kwargs_and_defaults.cpp``.
+
+.. note::
+
+    When combining \*args or \*\*kwargs with :ref:`keyword_args` you should
+    *not* include ``py::arg`` tags for the ``py::args`` and ``py::kwargs``
+    arguments.
 
 Default arguments revisited
 ===========================
@@ -309,3 +321,89 @@ like so:
 
     py::class_<MyClass>("MyClass")
         .def("myFunction", py::arg("arg") = (SomeType *) nullptr);
+
+.. _nonconverting_arguments:
+
+Non-converting arguments
+========================
+
+Certain argument types may support conversion from one type to another.  Some
+examples of conversions are:
+
+* :ref:`implicit_conversions` declared using ``py::implicitly_convertible<A,B>()``
+* Calling a method accepting a double with an integer argument
+* Calling a ``std::complex<float>`` argument with a non-complex python type
+  (for example, with a float).  (Requires the optional ``pybind11/complex.h``
+  header).
+* Calling a function taking an Eigen matrix reference with a numpy array of the
+  wrong type or of an incompatible data layout.  (Requires the optional
+  ``pybind11/eigen.h`` header).
+
+This behaviour is sometimes undesirable: the binding code may prefer to raise
+an error rather than convert the argument.  This behaviour can be obtained
+through ``py::arg`` by calling the ``.noconvert()`` method of the ``py::arg``
+object, such as:
+
+.. code-block:: cpp
+
+    m.def("floats_only", [](double f) { return 0.5 * f; }, py::arg("f").noconvert());
+    m.def("floats_preferred", [](double f) { return 0.5 * f; }, py::arg("f"));
+
+Attempting the call the second function (the one without ``.noconvert()``) with
+an integer will succeed, but attempting to call the ``.noconvert()`` version
+will fail with a ``TypeError``:
+
+.. code-block:: pycon
+
+    >>> floats_preferred(4)
+    2.0
+    >>> floats_only(4)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: floats_only(): incompatible function arguments. The following argument types are supported:
+        1. (f: float) -> float
+
+    Invoked with: 4
+
+You may, of course, combine this with the :var:`_a` shorthand notation (see
+:ref:`keyword_args`) and/or :ref:`default_args`.  It is also permitted to omit
+the argument name by using the ``py::arg()`` constructor without an argument
+name, i.e. by specifying ``py::arg().noconvert()``.
+
+.. note::
+
+    When specifying ``py::arg`` options it is necessary to provide the same
+    number of options as the bound function has arguments.  Thus if you want to
+    enable no-convert behaviour for just one of several arguments, you will
+    need to specify a ``py::arg()`` annotation for each argument with the
+    no-convert argument modified to ``py::arg().noconvert()``.
+
+Overload resolution order
+=========================
+
+When a function or method with multiple overloads is called from Python,
+pybind11 determines which overload to call in two passes.  The first pass
+attempts to call each overload without allowing argument conversion (as if
+every argument had been specified as ``py::arg().noconvert()`` as decribed
+above).
+
+If no overload succeeds in the no-conversion first pass, a second pass is
+attempted in which argument conversion is allowed (except where prohibited via
+an explicit ``py::arg().noconvert()`` attribute in the function definition).
+
+If the second pass also fails a ``TypeError`` is raised.
+
+Within each pass, overloads are tried in the order they were registered with
+pybind11.
+
+What this means in practice is that pybind11 will prefer any overload that does
+not require conversion of arguments to an overload that does, but otherwise prefers
+earlier-defined overloads to later-defined ones.
+
+.. note::
+
+    pybind11 does *not* further prioritize based on the number/pattern of
+    overloaded arguments.  That is, pybind11 does not prioritize a function
+    requiring one conversion over one requiring three, but only prioritizes
+    overloads requiring no conversion at all to overloads that require
+    conversion of at least one argument.
diff --git a/ext/pybind11/docs/advanced/misc.rst b/ext/pybind11/docs/advanced/misc.rst
index c13df7bf8..d98466512 100644
--- a/ext/pybind11/docs/advanced/misc.rst
+++ b/ext/pybind11/docs/advanced/misc.rst
@@ -19,6 +19,7 @@ another name and use it in the macro to avoid this problem.
 Global Interpreter Lock (GIL)
 =============================
 
+When calling a C++ function from Python, the GIL is always held.
 The classes :class:`gil_scoped_release` and :class:`gil_scoped_acquire` can be
 used to acquire and release the global interpreter lock in the body of a C++
 function call. In this way, long-running C++ code can be parallelized using
@@ -169,6 +170,20 @@ would be then able to access the data behind the same pointer.
 
 .. [#f6] https://docs.python.org/3/extending/extending.html#using-capsules
 
+Module Destructors
+==================
+
+pybind11 does not provide an explicit mechanism to invoke cleanup code at
+module destruction time. In rare cases where such functionality is required, it
+is possible to emulate it using Python capsules with a destruction callback.
+
+.. code-block:: cpp
+
+    auto cleanup_callback = []() {
+        // perform cleanup here -- this function is called with the GIL held
+    };
+
+    m.add_object("_cleanup", py::capsule(cleanup_callback));
 
 Generating documentation using Sphinx
 =====================================
diff --git a/ext/pybind11/docs/advanced/pycpp/numpy.rst b/ext/pybind11/docs/advanced/pycpp/numpy.rst
index 8b46b7c83..6bcc46719 100644
--- a/ext/pybind11/docs/advanced/pycpp/numpy.rst
+++ b/ext/pybind11/docs/advanced/pycpp/numpy.rst
@@ -33,7 +33,7 @@ completely avoid copy operations with Python expressions like
 
 .. code-block:: cpp
 
-    py::class_<Matrix>(m, "Matrix")
+    py::class_<Matrix>(m, "Matrix", py::buffer_protocol())
        .def_buffer([](Matrix &m) -> py::buffer_info {
             return py::buffer_info(
                 m.data(),                               /* Pointer to buffer */
@@ -46,9 +46,12 @@ completely avoid copy operations with Python expressions like
             );
         });
 
-The snippet above binds a lambda function, which can create ``py::buffer_info``
-description records on demand describing a given matrix. The contents of
-``py::buffer_info`` mirror the Python buffer protocol specification.
+Supporting the buffer protocol in a new type involves specifying the special
+``py::buffer_protocol()`` tag in the ``py::class_`` constructor and calling the
+``def_buffer()`` method with a lambda function that creates a
+``py::buffer_info`` description record on demand describing a given matrix
+instance. The contents of ``py::buffer_info`` mirror the Python buffer protocol
+specification.
 
 .. code-block:: cpp
 
@@ -77,7 +80,7 @@ buffer objects (e.g. a NumPy matrix).
     typedef Matrix::Scalar Scalar;
     constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit;
 
-    py::class_<Matrix>(m, "Matrix")
+    py::class_<Matrix>(m, "Matrix", py::buffer_protocol())
         .def("__init__", [](Matrix &m, py::buffer b) {
             typedef Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic> Strides;
 
@@ -152,7 +155,7 @@ NumPy array containing double precision values.
 When it is invoked with a different type (e.g. an integer or a list of
 integers), the binding code will attempt to cast the input into a NumPy array
 of the requested type. Note that this feature requires the
-:file:``pybind11/numpy.h`` header to be included.
+:file:`pybind11/numpy.h` header to be included.
 
 Data in NumPy arrays is not guaranteed to packed in a dense manner;
 furthermore, entries can be separated by arbitrary column and row strides.
@@ -173,9 +176,10 @@ function overload.
 Structured types
 ================
 
-In order for ``py::array_t`` to work with structured (record) types, we first need
-to register the memory layout of the type. This can be done via ``PYBIND11_NUMPY_DTYPE``
-macro which expects the type followed by field names:
+In order for ``py::array_t`` to work with structured (record) types, we first
+need to register the memory layout of the type. This can be done via
+``PYBIND11_NUMPY_DTYPE`` macro, called in the plugin definition code, which
+expects the type followed by field names:
 
 .. code-block:: cpp
 
@@ -189,10 +193,14 @@ macro which expects the type followed by field names:
         A a;
     };
 
-    PYBIND11_NUMPY_DTYPE(A, x, y);
-    PYBIND11_NUMPY_DTYPE(B, z, a);
+    // ...
+    PYBIND11_PLUGIN(test) {
+        // ...
 
-    /* now both A and B can be used as template arguments to py::array_t */
+        PYBIND11_NUMPY_DTYPE(A, x, y);
+        PYBIND11_NUMPY_DTYPE(B, z, a);
+        /* now both A and B can be used as template arguments to py::array_t */
+    }
 
 Vectorizing functions
 =====================
@@ -297,3 +305,75 @@ simply using ``vectorize``).
 
     The file :file:`tests/test_numpy_vectorize.cpp` contains a complete
     example that demonstrates using :func:`vectorize` in more detail.
+
+Direct access
+=============
+
+For performance reasons, particularly when dealing with very large arrays, it
+is often desirable to directly access array elements without internal checking
+of dimensions and bounds on every access when indices are known to be already
+valid.  To avoid such checks, the ``array`` class and ``array_t<T>`` template
+class offer an unchecked proxy object that can be used for this unchecked
+access through the ``unchecked<N>`` and ``mutable_unchecked<N>`` methods,
+where ``N`` gives the required dimensionality of the array:
+
+.. code-block:: cpp
+
+    m.def("sum_3d", [](py::array_t<double> x) {
+        auto r = x.unchecked<3>(); // x must have ndim = 3; can be non-writeable
+        double sum = 0;
+        for (size_t i = 0; i < r.shape(0); i++)
+            for (size_t j = 0; j < r.shape(1); j++)
+                for (size_t k = 0; k < r.shape(2); k++)
+                    sum += r(i, j, k);
+        return sum;
+    });
+    m.def("increment_3d", [](py::array_t<double> x) {
+        auto r = x.mutable_unchecked<3>(); // Will throw if ndim != 3 or flags.writeable is false
+        for (size_t i = 0; i < r.shape(0); i++)
+            for (size_t j = 0; j < r.shape(1); j++)
+                for (size_t k = 0; k < r.shape(2); k++)
+                    r(i, j, k) += 1.0;
+    }, py::arg().noconvert());
+
+To obtain the proxy from an ``array`` object, you must specify both the data
+type and number of dimensions as template arguments, such as ``auto r =
+myarray.mutable_unchecked<float, 2>()``.
+
+If the number of dimensions is not known at compile time, you can omit the
+dimensions template parameter (i.e. calling ``arr_t.unchecked()`` or
+``arr.unchecked<T>()``.  This will give you a proxy object that works in the
+same way, but results in less optimizable code and thus a small efficiency
+loss in tight loops.
+
+Note that the returned proxy object directly references the array's data, and
+only reads its shape, strides, and writeable flag when constructed.  You must
+take care to ensure that the referenced array is not destroyed or reshaped for
+the duration of the returned object, typically by limiting the scope of the
+returned instance.
+
+The returned proxy object supports some of the same methods as ``py::array`` so
+that it can be used as a drop-in replacement for some existing, index-checked
+uses of ``py::array``:
+
+- ``r.ndim()`` returns the number of dimensions
+
+- ``r.data(1, 2, ...)`` and ``r.mutable_data(1, 2, ...)``` returns a pointer to
+  the ``const T`` or ``T`` data, respectively, at the given indices.  The
+  latter is only available to proxies obtained via ``a.mutable_unchecked()``.
+
+- ``itemsize()`` returns the size of an item in bytes, i.e. ``sizeof(T)``.
+
+- ``ndim()`` returns the number of dimensions.
+
+- ``shape(n)`` returns the size of dimension ``n``
+
+- ``size()`` returns the total number of elements (i.e. the product of the shapes).
+
+- ``nbytes()`` returns the number of bytes used by the referenced elements
+  (i.e. ``itemsize()`` times ``size()``).
+
+.. seealso::
+
+    The file :file:`tests/test_numpy_array.cpp` contains additional examples
+    demonstrating the use of this feature.
diff --git a/ext/pybind11/docs/advanced/pycpp/object.rst b/ext/pybind11/docs/advanced/pycpp/object.rst
index 8fc165d16..ae58876de 100644
--- a/ext/pybind11/docs/advanced/pycpp/object.rst
+++ b/ext/pybind11/docs/advanced/pycpp/object.rst
@@ -33,6 +33,8 @@ The reverse direction uses the following syntax:
 
 When conversion fails, both directions throw the exception :class:`cast_error`.
 
+.. _calling_python_functions:
+
 Calling Python functions
 ========================
 
@@ -57,7 +59,7 @@ In C++, the same call can be made using:
 
 .. code-block:: cpp
 
-    using pybind11::literals; // to bring in the `_a` literal
+    using namespace pybind11::literals; // to bring in the `_a` literal
     f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++
 
 Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with
diff --git a/ext/pybind11/docs/advanced/smart_ptrs.rst b/ext/pybind11/docs/advanced/smart_ptrs.rst
index 23072b6bf..e4a238603 100644
--- a/ext/pybind11/docs/advanced/smart_ptrs.rst
+++ b/ext/pybind11/docs/advanced/smart_ptrs.rst
@@ -123,7 +123,7 @@ Custom smart pointers
 pybind11 supports ``std::unique_ptr`` and ``std::shared_ptr`` right out of the
 box. For any other custom smart pointer, transparent conversions can be enabled
 using a macro invocation similar to the following. It must be declared at the
-level before any binding code:
+top namespace level before any binding code:
 
 .. code-block:: cpp
 
@@ -134,8 +134,42 @@ placeholder name that is used as a template parameter of the second argument.
 Thus, feel free to use any identifier, but use it consistently on both sides;
 also, don't use the name of a type that already exists in your codebase.
 
+The macro also accepts a third optional boolean parameter that is set to false
+by default. Specify
+
+.. code-block:: cpp
+
+    PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>, true);
+
+if ``SmartPtr<T>`` can always be initialized from a ``T*`` pointer without the
+risk of inconsistencies (such as multiple independent ``SmartPtr`` instances
+believing that they are the sole owner of the ``T*`` pointer). A common
+situation where ``true`` should be passed is when the ``T`` instances use
+*intrusive* reference counting.
+
 Please take a look at the :ref:`macro_notes` before using this feature.
 
+By default, pybind11 assumes that your custom smart pointer has a standard
+interface, i.e. provides a ``.get()`` member function to access the underlying
+raw pointer. If this is not the case, pybind11's ``holder_helper`` must be
+specialized:
+
+.. code-block:: cpp
+
+    // Always needed for custom holder types
+    PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>);
+
+    // Only needed if the type's `.get()` goes by another name
+    namespace pybind11 { namespace detail {
+        template <typename T>
+        struct holder_helper<SmartPtr<T>> { // <-- specialization
+            static const T *get(const SmartPtr<T> &p) { return p.getPointer(); }
+        };
+    }}
+
+The above specialization informs pybind11 that the custom ``SmartPtr`` class
+provides ``.get()`` functionality via ``.getPointer()``.
+
 .. seealso::
 
     The file :file:`tests/test_smart_ptr.cpp` contains a complete example
diff --git a/ext/pybind11/docs/basics.rst b/ext/pybind11/docs/basics.rst
index c1dd47412..33c60049d 100644
--- a/ext/pybind11/docs/basics.rst
+++ b/ext/pybind11/docs/basics.rst
@@ -25,7 +25,7 @@ After installing the prerequisites, run
    mkdir build
    cd build
    cmake ..
-   make pytest -j 4
+   make check -j 4
 
 The last line will both compile and run the tests.
 
@@ -42,7 +42,7 @@ To compile and run the tests:
    mkdir build
    cd build
    cmake ..
-   cmake --build . --config Release --target pytest
+   cmake --build . --config Release --target check
 
 This will create a Visual Studio project, compile and run the target, all from the
 command line.
diff --git a/ext/pybind11/docs/changelog.rst b/ext/pybind11/docs/changelog.rst
index 15cf8d959..aba8a2009 100644
--- a/ext/pybind11/docs/changelog.rst
+++ b/ext/pybind11/docs/changelog.rst
@@ -3,64 +3,410 @@
 Changelog
 #########
 
-Starting with version 1.8, pybind11 releases use a
-[semantic versioning](http://semver.org) policy.
+Starting with version 1.8.0, pybind11 releases use a `semantic versioning
+<http://semver.org>`_ policy.
 
-Breaking changes queued for v2.0.0 (Not yet released)
+
+v2.1.1 (April 7, 2017)
 -----------------------------------------------------
-* Redesigned virtual call mechanism and user-facing syntax (see
-  https://github.com/pybind/pybind11/commit/86d825f3302701d81414ddd3d38bcd09433076bc)
 
-* Remove ``handle.call()`` method
+* Fixed minimum version requirement for MSVC 2015u3
+  `#773 <https://github.com/pybind/pybind11/pull/773>`_.
+
+v2.1.0 (March 22, 2017)
+-----------------------------------------------------
+
+* pybind11 now performs function overload resolution in two phases. The first
+  phase only considers exact type matches, while the second allows for implicit
+  conversions to take place. A special ``noconvert()`` syntax can be used to
+  completely disable implicit conversions for specific arguments.
+  `#643 <https://github.com/pybind/pybind11/pull/643>`_,
+  `#634 <https://github.com/pybind/pybind11/pull/634>`_,
+  `#650 <https://github.com/pybind/pybind11/pull/650>`_.
+
+* Fixed a regression where static properties no longer worked with classes
+  using multiple inheritance. The ``py::metaclass`` attribute is no longer
+  necessary (and deprecated as of this release) when binding classes with
+  static properties.
+  `#679 <https://github.com/pybind/pybind11/pull/679>`_,
+
+* Classes bound using ``pybind11`` can now use custom metaclasses.
+  `#679 <https://github.com/pybind/pybind11/pull/679>`_,
+
+* ``py::args`` and ``py::kwargs`` can now be mixed with other positional
+  arguments when binding functions using pybind11.
+  `#611 <https://github.com/pybind/pybind11/pull/611>`_.
+
+* Improved support for C++11 unicode string and character types; added
+  extensive documentation regarding pybind11's string conversion behavior.
+  `#624 <https://github.com/pybind/pybind11/pull/624>`_,
+  `#636 <https://github.com/pybind/pybind11/pull/636>`_,
+  `#715 <https://github.com/pybind/pybind11/pull/715>`_.
+
+* pybind11 can now avoid expensive copies when converting Eigen arrays to NumPy
+  arrays (and vice versa). `#610 <https://github.com/pybind/pybind11/pull/610>`_.
+
+* The "fast path" in ``py::vectorize`` now works for any full-size group of C or
+  F-contiguous arrays. The non-fast path is also faster since it no longer performs
+  copies of the input arguments (except when type conversions are necessary).
+  `#610 <https://github.com/pybind/pybind11/pull/610>`_.
+
+* Added fast, unchecked access to NumPy arrays via a proxy object.
+  `#746 <https://github.com/pybind/pybind11/pull/746>`_.
+
+* Transparent support for class-specific ``operator new`` and
+  ``operator delete`` implementations.
+  `#755 <https://github.com/pybind/pybind11/pull/755>`_.
+
+* Slimmer and more efficient STL-compatible iterator interface for sequence types.
+  `#662 <https://github.com/pybind/pybind11/pull/662>`_.
+
+* Improved custom holder type support.
+  `#607 <https://github.com/pybind/pybind11/pull/607>`_.
+
+* ``nullptr`` to ``None`` conversion fixed in various builtin type casters.
+  `#732 <https://github.com/pybind/pybind11/pull/732>`_.
+
+* ``enum_`` now exposes its members via a special ``__members__`` attribute.
+  `#666 <https://github.com/pybind/pybind11/pull/666>`_.
+
+* ``std::vector`` bindings created using ``stl_bind.h`` can now optionally
+  implement the buffer protocol. `#488 <https://github.com/pybind/pybind11/pull/488>`_.
+
+* Automated C++ reference documentation using doxygen and breathe.
+  `#598 <https://github.com/pybind/pybind11/pull/598>`_.
+
+* Added minimum compiler version assertions.
+  `#727 <https://github.com/pybind/pybind11/pull/727>`_.
+
+* Improved compatibility with C++1z.
+  `#677 <https://github.com/pybind/pybind11/pull/677>`_.
+
+* Improved ``py::capsule`` API. Can be used to implement cleanup
+  callbacks that are involved at module destruction time.
+  `#752 <https://github.com/pybind/pybind11/pull/752>`_.
+
+* Various minor improvements and fixes.
+  `#595 <https://github.com/pybind/pybind11/pull/595>`_,
+  `#588 <https://github.com/pybind/pybind11/pull/588>`_,
+  `#589 <https://github.com/pybind/pybind11/pull/589>`_,
+  `#603 <https://github.com/pybind/pybind11/pull/603>`_,
+  `#619 <https://github.com/pybind/pybind11/pull/619>`_,
+  `#648 <https://github.com/pybind/pybind11/pull/648>`_,
+  `#695 <https://github.com/pybind/pybind11/pull/695>`_,
+  `#720 <https://github.com/pybind/pybind11/pull/720>`_,
+  `#723 <https://github.com/pybind/pybind11/pull/723>`_,
+  `#729 <https://github.com/pybind/pybind11/pull/729>`_,
+  `#724 <https://github.com/pybind/pybind11/pull/724>`_,
+  `#742 <https://github.com/pybind/pybind11/pull/742>`_,
+  `#753 <https://github.com/pybind/pybind11/pull/753>`_.
+
+v2.0.1 (Jan 4, 2017)
+-----------------------------------------------------
+
+* Fix pointer to reference error in type_caster on MSVC
+  `#583 <https://github.com/pybind/pybind11/pull/583>`_.
+
+* Fixed a segmentation in the test suite due to a typo
+  `cd7eac <https://github.com/pybind/pybind11/commit/cd7eac>`_.
+
+v2.0.0 (Jan 1, 2017)
+-----------------------------------------------------
+
+* Fixed a reference counting regression affecting types with custom metaclasses
+  (introduced in v2.0.0-rc1).
+  `#571 <https://github.com/pybind/pybind11/pull/571>`_.
+
+* Quenched a CMake policy warning.
+  `#570 <https://github.com/pybind/pybind11/pull/570>`_.
+
+v2.0.0-rc1 (Dec 23, 2016)
+-----------------------------------------------------
+
+The pybind11 developers are excited to issue a release candidate of pybind11
+with a subsequent v2.0.0 release planned in early January next year.
+
+An incredible amount of effort by went into pybind11 over the last ~5 months,
+leading to a release that is jam-packed with exciting new features and numerous
+usability improvements. The following list links PRs or individual commits
+whenever applicable.
+
+Happy Christmas!
+
+* Support for binding C++ class hierarchies that make use of multiple
+  inheritance. `#410 <https://github.com/pybind/pybind11/pull/410>`_.
+
+* PyPy support: pybind11 now supports nightly builds of PyPy and will
+  interoperate with the future 5.7 release. No code changes are necessary,
+  everything "just" works as usual. Note that we only target the Python 2.7
+  branch for now; support for 3.x will be added once its ``cpyext`` extension
+  support catches up. A few minor features remain unsupported for the time
+  being (notably dynamic attributes in custom types).
+  `#527 <https://github.com/pybind/pybind11/pull/527>`_.
+
+* Significant work on the documentation -- in particular, the monolitic
+  ``advanced.rst`` file was restructured into a easier to read hierarchical
+  organization. `#448 <https://github.com/pybind/pybind11/pull/448>`_.
+
+* Many NumPy-related improvements:
+
+  1. Object-oriented API to access and modify NumPy ``ndarray`` instances,
+     replicating much of the corresponding NumPy C API functionality.
+     `#402 <https://github.com/pybind/pybind11/pull/402>`_.
+
+  2. NumPy array ``dtype`` array descriptors are now first-class citizens and
+     are exposed via a new class ``py::dtype``.
+
+  3. Structured dtypes can be registered using the ``PYBIND11_NUMPY_DTYPE()``
+     macro. Special ``array`` constructors accepting dtype objects were also
+     added.
+
+     One potential caveat involving this change: format descriptor strings
+     should now be accessed via ``format_descriptor::format()`` (however, for
+     compatibility purposes, the old syntax ``format_descriptor::value`` will
+     still work for non-structured data types). `#308
+     <https://github.com/pybind/pybind11/pull/308>`_.
+
+  4. Further improvements to support structured dtypes throughout the system.
+     `#472 <https://github.com/pybind/pybind11/pull/472>`_,
+     `#474 <https://github.com/pybind/pybind11/pull/474>`_,
+     `#459 <https://github.com/pybind/pybind11/pull/459>`_,
+     `#453 <https://github.com/pybind/pybind11/pull/453>`_,
+     `#452 <https://github.com/pybind/pybind11/pull/452>`_, and
+     `#505 <https://github.com/pybind/pybind11/pull/505>`_.
+
+  5. Fast access operators. `#497 <https://github.com/pybind/pybind11/pull/497>`_.
+
+  6. Constructors for arrays whose storage is owned by another object.
+     `#440 <https://github.com/pybind/pybind11/pull/440>`_.
+
+  7. Added constructors for ``array`` and ``array_t`` explicitly accepting shape
+     and strides; if strides are not provided, they are deduced assuming
+     C-contiguity. Also added simplified constructors for 1-dimensional case.
+
+  8. Added buffer/NumPy support for ``char[N]`` and ``std::array<char, N>`` types.
+
+  9. Added ``memoryview`` wrapper type which is constructible from ``buffer_info``.
+
+* Eigen: many additional conversions and support for non-contiguous
+  arrays/slices.
+  `#427 <https://github.com/pybind/pybind11/pull/427>`_,
+  `#315 <https://github.com/pybind/pybind11/pull/315>`_,
+  `#316 <https://github.com/pybind/pybind11/pull/316>`_,
+  `#312 <https://github.com/pybind/pybind11/pull/312>`_, and
+  `#267 <https://github.com/pybind/pybind11/pull/267>`_
+
+* Incompatible changes in ``class_<...>::class_()``:
+
+    1. Declarations of types that provide access via the buffer protocol must
+       now include the ``py::buffer_protocol()`` annotation as an argument to
+       the ``class_`` constructor.
+
+    2. Declarations of types that require a custom metaclass (i.e. all classes
+       which include static properties via commands such as
+       ``def_readwrite_static()``) must now include the ``py::metaclass()``
+       annotation as an argument to the ``class_`` constructor.
+
+       These two changes were necessary to make type definitions in pybind11
+       future-proof, and to support PyPy via its cpyext mechanism. `#527
+       <https://github.com/pybind/pybind11/pull/527>`_.
+
+
+    3. This version of pybind11 uses a redesigned mechnism for instantiating
+       trempoline classes that are used to override virtual methods from within
+       Python. This led to the following user-visible syntax change: instead of
+
+       .. code-block:: cpp
+
+           py::class_<TrampolineClass>("MyClass")
+             .alias<MyClass>()
+             ....
+
+       write
+
+       .. code-block:: cpp
+
+           py::class_<MyClass, TrampolineClass>("MyClass")
+             ....
+
+       Importantly, both the original and the trampoline class are now
+       specified as an arguments (in arbitrary order) to the ``py::class_``
+       template, and the ``alias<..>()`` call is gone. The new scheme has zero
+       overhead in cases when Python doesn't override any functions of the
+       underlying C++ class. `rev. 86d825
+       <https://github.com/pybind/pybind11/commit/86d825>`_.
 
-1.9.0 (Not yet released)
-------------------------
-* Queued changes: map indexing suite, documentation for indexing suites.
-* Mapping a stateless C++ function to Python and back is now "for free" (i.e. no call overheads)
-* Support for translation of arbitrary C++ exceptions to Python counterparts
 * Added ``eval`` and ``eval_file`` functions for evaluating expressions and
-  statements from a string or file
-* eigen.h type converter fixed for non-contiguous arrays (e.g. slices)
-* Print more informative error messages when ``make_tuple()`` or ``cast()`` fail
-* ``std::enable_shared_from_this<>`` now also works for ``const`` values
-* A return value policy can now be passed to ``handle::operator()``
-* ``make_iterator()`` improvements for better compatibility with various types
-  (now uses prefix increment operator); it now also accepts iterators with
-  different begin/end types as long as they are equality comparable.
-* ``arg()`` now accepts a wider range of argument types for default values
-* Added ``py::repr()`` function which is equivalent to Python's builtin ``repr()``.
-* Added support for registering structured dtypes via ``PYBIND11_NUMPY_DTYPE()`` macro.
-* Added ``PYBIND11_STR_TYPE`` macro which maps to the ``builtins.str`` type.
-* Added a simplified ``buffer_info`` constructor for 1-dimensional buffers.
-* Format descriptor strings should now be accessed via ``format_descriptor::format()``
-  (for compatibility purposes, the old syntax ``format_descriptor::value`` will still
-  work for non-structured data types).
-* Added a class wrapping NumPy array descriptors: ``dtype``.
-* Added buffer/NumPy support for ``char[N]`` and ``std::array<char, N>`` types.
-* ``array`` gained new constructors accepting dtype objects.
-* Added constructors for ``array`` and ``array_t`` explicitly accepting shape and
-  strides; if strides are not provided, they are deduced assuming C-contiguity.
-  Also added simplified constructors for 1-dimensional case.
-* Added constructors for ``str`` from ``bytes`` and for ``bytes`` from ``str``.
-  This will do the UTF-8 decoding/encoding as required.
-* Added constructors for ``str`` and ``bytes`` from zero-terminated char pointers,
-  and from char pointers and length.
-* Added ``memoryview`` wrapper type which is constructible from ``buffer_info``.
-* New syntax to call a Python function from C++ using keyword arguments and unpacking,
-  e.g. ``foo(1, 2, "z"_a=3)`` or ``bar(1, *args, "z"_a=3, **kwargs)``.
-* Added ``py::print()`` function which replicates Python's API and writes to Python's
-  ``sys.stdout`` by default (as opposed to C's ``stdout`` like ``std::cout``).
-* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42, "name"_a="World");``
-* Added ``py::str::format()`` method and ``_s`` literal:
-  ``py::str s = "1 + 2 = {}"_s.format(3);``
-* Attribute and item accessors now have a more complete interface which makes it possible
-  to chain attributes ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)```.
-* Added built-in support for ``std::shared_ptr`` holder type. There is no more need
-  to do it manually via ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>)``.
-* Default return values policy changes: non-static properties now use ``reference_internal``
-  and static properties use ``reference`` (previous default was ``automatic``, i.e. ``copy``).
-* Support for ``std::experimental::optional<T>`` and ``std::optional<T>`` (C++17).
-* Various minor improvements of library internals (no user-visible changes)
+  statements from a string or file. `rev. 0d3fc3
+  <https://github.com/pybind/pybind11/commit/0d3fc3>`_.
+
+* pybind11 can now create types with a modifiable dictionary.
+  `#437 <https://github.com/pybind/pybind11/pull/437>`_ and
+  `#444 <https://github.com/pybind/pybind11/pull/444>`_.
+
+* Support for translation of arbitrary C++ exceptions to Python counterparts.
+  `#296 <https://github.com/pybind/pybind11/pull/296>`_ and
+  `#273 <https://github.com/pybind/pybind11/pull/273>`_.
+
+* Report full backtraces through mixed C++/Python code, better reporting for
+  import errors, fixed GIL management in exception processing.
+  `#537 <https://github.com/pybind/pybind11/pull/537>`_,
+  `#494 <https://github.com/pybind/pybind11/pull/494>`_,
+  `rev. e72d95 <https://github.com/pybind/pybind11/commit/e72d95>`_, and
+  `rev. 099d6e <https://github.com/pybind/pybind11/commit/099d6e>`_.
+
+* Support for bit-level operations, comparisons, and serialization of C++
+  enumerations. `#503 <https://github.com/pybind/pybind11/pull/503>`_,
+  `#508 <https://github.com/pybind/pybind11/pull/508>`_,
+  `#380 <https://github.com/pybind/pybind11/pull/380>`_,
+  `#309 <https://github.com/pybind/pybind11/pull/309>`_.
+  `#311 <https://github.com/pybind/pybind11/pull/311>`_.
+
+* The ``class_`` constructor now accepts its template arguments in any order.
+  `#385 <https://github.com/pybind/pybind11/pull/385>`_.
+
+* Attribute and item accessors now have a more complete interface which makes
+  it possible to chain attributes as in
+  ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)``. `#425
+  <https://github.com/pybind/pybind11/pull/425>`_.
+
+* Major redesign of the default and conversion constructors in ``pytypes.h``.
+  `#464 <https://github.com/pybind/pybind11/pull/464>`_.
+
+* Added built-in support for ``std::shared_ptr`` holder type. It is no longer
+  necessary to to include a declaration of the form
+  ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>)`` (though continuing to
+  do so won't cause an error).
+  `#454 <https://github.com/pybind/pybind11/pull/454>`_.
+
+* New ``py::overload_cast`` casting operator to select among multiple possible
+  overloads of a function. An example:
+
+    .. code-block:: cpp
+
+        py::class_<Pet>(m, "Pet")
+            .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age")
+            .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name");
+
+  This feature only works on C++14-capable compilers.
+  `#541 <https://github.com/pybind/pybind11/pull/541>`_.
+
+* C++ types are automatically cast to Python types, e.g. when assigning
+  them as an attribute. For instance, the following is now legal:
+
+    .. code-block:: cpp
+
+        py::module m = /* ... */
+        m.attr("constant") = 123;
+
+  (Previously, a ``py::cast`` call was necessary to avoid a compilation error.)
+  `#551 <https://github.com/pybind/pybind11/pull/551>`_.
+
+* Redesigned ``pytest``-based test suite. `#321 <https://github.com/pybind/pybind11/pull/321>`_.
+
+* Instance tracking to detect reference leaks in test suite. `#324 <https://github.com/pybind/pybind11/pull/324>`_
+
+* pybind11 can now distinguish between multiple different instances that are
+  located at the same memory address, but which have different types.
+  `#329 <https://github.com/pybind/pybind11/pull/329>`_.
+
+* Improved logic in ``move`` return value policy.
+  `#510 <https://github.com/pybind/pybind11/pull/510>`_,
+  `#297 <https://github.com/pybind/pybind11/pull/297>`_.
+
+* Generalized unpacking API to permit calling Python functions from C++ using
+  notation such as ``foo(a1, a2, *args, "ka"_a=1, "kb"_a=2, **kwargs)``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
+
+* ``py::print()`` function whose behavior matches that of the native Python
+  ``print()`` function. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
+
+* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42,
+  "name"_a="World");``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
+
+* Added ``py::str::format()`` method and ``_s`` literal: ``py::str s = "1 + 2
+  = {}"_s.format(3);``. `#372 <https://github.com/pybind/pybind11/pull/372>`_.
+
+* Added ``py::repr()`` function which is equivalent to Python's builtin
+  ``repr()``. `#333 <https://github.com/pybind/pybind11/pull/333>`_.
+
+* Improved construction and destruction logic for holder types. It is now
+  possible to reference instances with smart pointer holder types without
+  constructing the holder if desired. The ``PYBIND11_DECLARE_HOLDER_TYPE``
+  macro now accepts an optional second parameter to indicate whether the holder
+  type uses intrusive reference counting.
+  `#533 <https://github.com/pybind/pybind11/pull/533>`_ and
+  `#561 <https://github.com/pybind/pybind11/pull/561>`_.
+
+* Mapping a stateless C++ function to Python and back is now "for free" (i.e.
+  no extra indirections or argument conversion overheads). `rev. 954b79
+  <https://github.com/pybind/pybind11/commit/954b79>`_.
+
+* Bindings for ``std::valarray<T>``.
+  `#545 <https://github.com/pybind/pybind11/pull/545>`_.
+
+* Improved support for C++17 capable compilers.
+  `#562 <https://github.com/pybind/pybind11/pull/562>`_.
+
+* Bindings for ``std::optional<t>``.
+  `#475 <https://github.com/pybind/pybind11/pull/475>`_,
+  `#476 <https://github.com/pybind/pybind11/pull/476>`_,
+  `#479 <https://github.com/pybind/pybind11/pull/479>`_,
+  `#499 <https://github.com/pybind/pybind11/pull/499>`_, and
+  `#501 <https://github.com/pybind/pybind11/pull/501>`_.
+
+* ``stl_bind.h``: general improvements and support for ``std::map`` and
+  ``std::unordered_map``.
+  `#490 <https://github.com/pybind/pybind11/pull/490>`_,
+  `#282 <https://github.com/pybind/pybind11/pull/282>`_,
+  `#235 <https://github.com/pybind/pybind11/pull/235>`_.
+
+* The ``std::tuple``, ``std::pair``, ``std::list``, and ``std::vector`` type
+  casters now accept any Python sequence type as input. `rev. 107285
+  <https://github.com/pybind/pybind11/commit/107285>`_.
+
+* Improved CMake Python detection on multi-architecture Linux.
+  `#532 <https://github.com/pybind/pybind11/pull/532>`_.
+
+* Infrastructure to selectively disable or enable parts of the automatically
+  generated docstrings. `#486 <https://github.com/pybind/pybind11/pull/486>`_.
+
+* ``reference`` and ``reference_internal`` are now the default return value
+  properties for static and non-static properties, respectively. `#473
+  <https://github.com/pybind/pybind11/pull/473>`_. (the previous defaults
+  were ``automatic``). `#473 <https://github.com/pybind/pybind11/pull/473>`_.
+
+* Support for ``std::unique_ptr`` with non-default deleters or no deleter at
+  all (``py::nodelete``). `#384 <https://github.com/pybind/pybind11/pull/384>`_.
+
+* Deprecated ``handle::call()`` method. The new syntax to call Python
+  functions is simply ``handle()``. It can also be invoked explicitly via
+  ``handle::operator<X>()``, where ``X`` is an optional return value policy.
+
+* Print more informative error messages when ``make_tuple()`` or ``cast()``
+  fail. `#262 <https://github.com/pybind/pybind11/pull/262>`_.
+
+* Creation of holder types for classes deriving from
+  ``std::enable_shared_from_this<>`` now also works for ``const`` values.
+  `#260 <https://github.com/pybind/pybind11/pull/260>`_.
+
+* ``make_iterator()`` improvements for better compatibility with various
+  types (now uses prefix increment operator); it now also accepts iterators
+  with different begin/end types as long as they are equality comparable.
+  `#247 <https://github.com/pybind/pybind11/pull/247>`_.
+
+* ``arg()`` now accepts a wider range of argument types for default values.
+  `#244 <https://github.com/pybind/pybind11/pull/244>`_.
+
+* Support ``keep_alive`` where the nurse object may be ``None``. `#341
+  <https://github.com/pybind/pybind11/pull/341>`_.
+
+* Added constructors for ``str`` and ``bytes`` from zero-terminated char
+  pointers, and from char pointers and length. Added constructors for ``str``
+  from ``bytes`` and for ``bytes`` from ``str``, which will perform UTF-8
+  decoding/encoding as required.
+
+* Many other improvements of library internals without user-visible changes
+
 
 1.8.1 (July 12, 2016)
 ----------------------
diff --git a/ext/pybind11/docs/classes.rst b/ext/pybind11/docs/classes.rst
index 872977684..30fb2a2d5 100644
--- a/ext/pybind11/docs/classes.rst
+++ b/ext/pybind11/docs/classes.rst
@@ -38,7 +38,7 @@ The binding code for ``Pet`` looks as follows:
         return m.ptr();
     }
 
-:class:`class_` creates bindings for a C++ `class` or `struct`-style data
+:class:`class_` creates bindings for a C++ *class* or *struct*-style data
 structure. :func:`init` is a convenience function that takes the types of a
 constructor's parameters as template arguments and wraps the corresponding
 constructor (see the :ref:`custom_constructors` section for details). An
@@ -298,8 +298,8 @@ different kinds of input arguments:
     struct Pet {
         Pet(const std::string &name, int age) : name(name), age(age) { }
 
-        void set(int age) { age = age; }
-        void set(const std::string &name) { name = name; }
+        void set(int age_) { age = age_; }
+        void set(const std::string &name_) { name = name_; }
 
         std::string name;
         int age;
@@ -423,6 +423,12 @@ typed enums.
     >>> int(p.type)
     1L
 
+The entries defined by the enumeration type are exposed in the ``__members__`` property:
+
+.. code-block:: pycon
+
+    >>> Pet.Kind.__members__
+    {'Dog': Kind.Dog, 'Cat': Kind.Cat}
 
 .. note::
 
diff --git a/ext/pybind11/docs/compiling.rst b/ext/pybind11/docs/compiling.rst
index 35768fe45..c7053dbf9 100644
--- a/ext/pybind11/docs/compiling.rst
+++ b/ext/pybind11/docs/compiling.rst
@@ -39,30 +39,88 @@ extension module can be created with just a few lines of code:
 
 This assumes that the pybind11 repository is located in a subdirectory named
 :file:`pybind11` and that the code is located in a file named :file:`example.cpp`.
-The CMake command ``add_subdirectory`` will import a function with the signature
-``pybind11_add_module(<name> source1 [source2 ...])``. It will take care of all
-the details needed to build a Python extension module on any platform.
-
-The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION``
-variable before adding the pybind11 subdirectory. Alternatively, an exact Python
-installation can be specified by setting ``PYTHON_EXECUTABLE``.
+The CMake command ``add_subdirectory`` will import the pybind11 project which
+provides the ``pybind11_add_module`` function. It will take care of all the
+details needed to build a Python extension module on any platform.
 
 A working sample project, including a way to invoke CMake from :file:`setup.py` for
 PyPI integration, can be found in the [cmake_example]_  repository.
 
 .. [cmake_example] https://github.com/pybind/cmake_example
 
-For CMake-based projects that don't include the pybind11
-repository internally, an external installation can be detected
-through `find_package(pybind11 ... CONFIG ...)`. See the `Config file
-<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_
-docstring for details of relevant CMake variables.
+pybind11_add_module
+-------------------
 
-Once detected, and after setting any variables to guide Python and
-C++ standard detection, the aforementioned ``pybind11_add_module``
-wrapper to ``add_library`` can be employed as described above (after
-``include(pybind11Tools)``). This procedure is available when using CMake
->= 2.8.12. A working example can be found at [test_installed_module]_ .
+To ease the creation of Python extension modules, pybind11 provides a CMake
+function with the following signature:
+
+.. code-block:: cmake
+
+    pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL]
+                        [NO_EXTRAS] [THIN_LTO] source1 [source2 ...])
+
+This function behaves very much like CMake's builtin ``add_library`` (in fact,
+it's a wrapper function around that command). It will add a library target
+called ``<name>`` to be built from the listed source files. In addition, it
+will take care of all the Python-specific compiler and linker flags as well
+as the OS- and Python-version-specific file extension. The produced target
+``<name>`` can be further manipulated with regular CMake commands.
+
+``MODULE`` or ``SHARED`` may be given to specify the type of library. If no
+type is given, ``MODULE`` is used by default which ensures the creation of a
+Python-exclusive module. Specifying ``SHARED`` will create a more traditional
+dynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL``
+removes this target from the default build (see CMake docs for details).
+
+Since pybind11 is a template library, ``pybind11_add_module`` adds compiler
+flags to ensure high quality code generation without bloat arising from long
+symbol names and duplication of code in different translation units. The
+additional flags enable LTO (Link Time Optimization), set default visibility
+to *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>`
+for a more detailed explanation. These optimizations are never applied in
+``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even
+in ``Release`` mode. However, this will result in code bloat and is generally
+not recommended.
+
+As stated above, LTO is enabled by default. Some newer compilers also support
+different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause
+the function to prefer this flavor if available. The function falls back to
+regular LTO if ``-flto=thin`` is not available.
+
+.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html
+
+Configuration variables
+-----------------------
+
+By default, pybind11 will compile modules with the latest C++ standard
+available on the target compiler. To override this, the standard flag can
+be given explicitly in ``PYBIND11_CPP_STANDARD``:
+
+.. code-block:: cmake
+
+    set(PYBIND11_CPP_STANDARD -std=c++11)
+    add_subdirectory(pybind11)  # or find_package(pybind11)
+
+Note that this and all other configuration variables must be set **before** the
+call to ``add_subdiretory`` or ``find_package``. The variables can also be set
+when calling CMake from the command line using the ``-D<variable>=<value>`` flag.
+
+The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``
+or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``.
+For example:
+
+.. code-block:: bash
+
+    cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
+    # or
+    cmake -DPYTHON_EXECUTABLE=path/to/python ..
+
+find_package vs. add_subdirectory
+---------------------------------
+
+For CMake-based projects that don't include the pybind11 repository internally,
+an external installation can be detected through ``find_package(pybind11)``.
+See the `Config file`_ docstring for details of relevant CMake variables.
 
 .. code-block:: cmake
 
@@ -72,28 +130,33 @@ wrapper to ``add_library`` can be employed as described above (after
     find_package(pybind11 REQUIRED)
     pybind11_add_module(example example.cpp)
 
-.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt
+Once detected, the aforementioned ``pybind11_add_module`` can be employed as
+before. The function usage and configuration variables are identical no matter
+if pybind11 is added as a subdirectory or found as an installed package. You
+can refer to the same [cmake_example]_ repository for a full sample project
+-- just swap out ``add_subdirectory`` for ``find_package``.
+
+.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in
+
+Advanced: interface library target
+----------------------------------
 
-When using a version of CMake greater than 3.0, pybind11 can
-additionally be used as a special *interface library* following the
-call to ``find_package``. CMake variables to guide Python and C++
-standard detection should be set *before* ``find_package``. When
-``find_package`` returns, the target ``pybind11::pybind11`` is
-available with pybind11 headers, Python headers and libraries as
-needed, and C++ compile definitions attached. This target is suitable
-for linking to an independently constructed (through ``add_library``,
-not ``pybind11_add_module``) target in the consuming project. A working
-example can be found at [test_installed_target]_ .
+When using a version of CMake greater than 3.0, pybind11 can additionally
+be used as a special *interface library* . The target ``pybind11::module``
+is available with pybind11 headers, Python headers and libraries as needed,
+and C++ compile definitions attached. This target is suitable for linking
+to an independently constructed (through ``add_library``, not
+``pybind11_add_module``) target in the consuming project.
 
 .. code-block:: cmake
 
     cmake_minimum_required(VERSION 3.0)
     project(example)
 
-    add_library(example MODULE main.cpp)
+    find_package(pybind11 REQUIRED)  # or add_subdirectory(pybind11)
 
-    find_package(pybind11 REQUIRED)
-    target_link_libraries(example PRIVATE pybind11::pybind11)
+    add_library(example MODULE main.cpp)
+    target_link_libraries(example PRIVATE pybind11::module)
     set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
                                              SUFFIX "${PYTHON_MODULE_EXTENSION}")
 
@@ -112,5 +175,11 @@ example can be found at [test_installed_target]_ .
     (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
     explanation on why these are needed.
 
-.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt
+Generating binding code automatically
+=====================================
+
+The ``Binder`` project is a tool for automatic generation of pybind11 binding
+code by introspecting existing C++ codebases using LLVM/Clang. See the
+[binder]_ documentation for details.
 
+.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html
diff --git a/ext/pybind11/docs/conf.py b/ext/pybind11/docs/conf.py
index 69f0cb337..09604cfeb 100644
--- a/ext/pybind11/docs/conf.py
+++ b/ext/pybind11/docs/conf.py
@@ -16,6 +16,7 @@
 import sys
 import os
 import shlex
+import subprocess
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -30,7 +31,11 @@ import shlex
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['breathe']
+
+breathe_projects = {'pybind11': '.build/doxygenxml/'}
+breathe_default_project = 'pybind11'
+breathe_domain_by_extension = {'h': 'cpp'}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
@@ -48,7 +53,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'pybind11'
-copyright = '2015, Wenzel Jakob'
+copyright = '2016, Wenzel Jakob'
 author = 'Wenzel Jakob'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -56,9 +61,9 @@ author = 'Wenzel Jakob'
 # built documents.
 #
 # The short X.Y version.
-version = '1.9'
+version = '2.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.9.dev0'
+release = '2.1.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -79,7 +84,7 @@ exclude_patterns = ['.build', 'release.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+default_role = 'any'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -306,3 +311,22 @@ texinfo_documents = [
 
 primary_domain = 'cpp'
 highlight_language = 'cpp'
+
+
+def generate_doxygen_xml(app):
+    build_dir = '.build'
+    if not os.path.exists(build_dir):
+        os.mkdir(build_dir)
+
+    try:
+        subprocess.call(['doxygen', '--version'])
+        retcode = subprocess.call(['doxygen'])
+        if retcode < 0:
+            sys.stderr.write("doxygen error code: {}\n".format(-retcode))
+    except OSError as e:
+        sys.stderr.write("doxygen execution failed: {}\n".format(e))
+
+
+def setup(app):
+    """Add hook for building doxygen xml when needed"""
+    app.connect("builder-inited", generate_doxygen_xml)
diff --git a/ext/pybind11/docs/intro.rst b/ext/pybind11/docs/intro.rst
index 429a01cdd..2149c18db 100644
--- a/ext/pybind11/docs/intro.rst
+++ b/ext/pybind11/docs/intro.rst
@@ -17,15 +17,14 @@ compatibility has its cost: arcane template tricks and workarounds are
 necessary to support the oldest and buggiest of compiler specimens. Now that
 C++11-compatible compilers are widely available, this heavy machinery has
 become an excessively large and unnecessary dependency.
-
 Think of this library as a tiny self-contained version of Boost.Python with
 everything stripped away that isn't relevant for binding generation. Without
-comments, the core header files only require ~2.5K lines of code and depend on
-Python (2.7 or 3.x) and the C++ standard library. This compact implementation
-was possible thanks to some of the new C++11 language features (specifically:
-tuples, lambda functions and variadic templates). Since its creation, this
-library has grown beyond Boost.Python in many ways, leading to dramatically
-simpler binding code in many common situations.
+comments, the core header files only require ~4K lines of code and depend on
+Python (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This
+compact implementation was possible thanks to some of the new C++11 language
+features (specifically: tuples, lambda functions and variadic templates). Since
+its creation, this library has grown beyond Boost.Python in many ways, leading
+to dramatically simpler binding code in many common situations.
 
 Core features
 *************
@@ -51,6 +50,9 @@ Goodies
 *******
 In addition to the core functionality, pybind11 provides some extra goodies:
 
+- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an
+  implementation-agnostic interface.
+
 - It is possible to bind C++11 lambda functions with captured variables. The
   lambda capture data is stored inside the resulting Python function object.
 
@@ -88,6 +90,6 @@ Supported compilers
 *******************
 
 1. Clang/LLVM (any non-ancient version with C++11 support)
-2. GCC (any non-ancient version with C++11 support)
+2. GCC 4.8 or newer
 3. Microsoft Visual Studio 2015 or newer
 4. Intel C++ compiler v15 or newer
diff --git a/ext/pybind11/docs/reference.rst b/ext/pybind11/docs/reference.rst
index 542259eba..3d211f7e9 100644
--- a/ext/pybind11/docs/reference.rst
+++ b/ext/pybind11/docs/reference.rst
@@ -12,236 +12,69 @@ Reference
 Macros
 ======
 
-.. function:: PYBIND11_PLUGIN(const char *name)
-
-    This macro creates the entry point that will be invoked when the Python
-    interpreter imports a plugin library. Please create a
-    :class:`module` in the function body and return the pointer to its
-    underlying Python object at the end.
-
-    .. code-block:: cpp
-
-        PYBIND11_PLUGIN(example) {
-            pybind11::module m("example", "pybind11 example plugin");
-            /// Set up bindings here
-            return m.ptr();
-        }
+.. doxygendefine:: PYBIND11_PLUGIN
 
 .. _core_types:
 
 Convenience classes for arbitrary Python types
 ==============================================
 
-Without reference counting
---------------------------
-
-.. class:: handle
-
-    The :class:`handle` class is a thin wrapper around an arbitrary Python
-    object (i.e. a ``PyObject *`` in Python's C API). It does not perform any
-    automatic reference counting and merely provides a basic C++ interface to
-    various Python API functions.
-
-.. seealso::
-
-    The :class:`object` class inherits from :class:`handle` and adds automatic
-    reference counting features.
-
-.. function:: handle::handle()
-
-    The default constructor creates a handle with a ``nullptr``-valued pointer.
-
-.. function:: handle::handle(const handle&)
-
-    Copy constructor
-
-.. function:: handle::handle(PyObject *)
-
-    Creates a :class:`handle` from the given raw Python object pointer.
-
-.. function:: PyObject * handle::ptr() const
-
-    Return the ``PyObject *`` underlying a :class:`handle`.
-
-.. function:: const handle& handle::inc_ref() const
-
-    Manually increase the reference count of the Python object. Usually, it is
-    preferable to use the :class:`object` class which derives from
-    :class:`handle` and calls this function automatically. Returns a reference
-    to itself.
-
-.. function:: const handle& handle::dec_ref() const
-
-    Manually decrease the reference count of the Python object. Usually, it is
-    preferable to use the :class:`object` class which derives from
-    :class:`handle` and calls this function automatically. Returns a reference
-    to itself.
-
-.. function:: void handle::ref_count() const
-
-    Return the object's current reference count
-
-.. function:: handle handle::get_type() const
-
-    Return a handle to the Python type object underlying the instance
-
-.. function detail::accessor handle::operator[](handle key) const
-
-    Return an internal functor to invoke the object's sequence protocol.
-    Casting the returned ``detail::accessor`` instance to a :class:`handle` or
-    :class:`object` subclass causes a corresponding call to ``__getitem__``.
-    Assigning a :class:`handle` or :class:`object` subclass causes a call to
-    ``__setitem__``.
-
-.. function detail::accessor handle::operator[](const char *key) const
-
-    See the above function (the only difference is that they key is provided as
-    a string literal).
-
-.. function detail::accessor handle::attr(handle key) const
-
-    Return an internal functor to access the object's attributes.
-    Casting the returned ``detail::accessor`` instance to a :class:`handle` or
-    :class:`object` subclass causes a corresponding call to ``__getattr``.
-    Assigning a :class:`handle` or :class:`object` subclass causes a call to
-    ``__setattr``.
-
-.. function detail::accessor handle::attr(const char *key) const
-
-    See the above function (the only difference is that they key is provided as
-    a string literal).
-
-.. function operator handle::bool() const
-
-    Return ``true`` when the :class:`handle` wraps a valid Python object.
-
-.. function str handle::str() const
-
-    Return a string representation of the object. This is analogous to
-    the ``str()`` function in Python.
-
-.. function:: template <typename T> T handle::cast() const
-
-    Attempt to cast the Python object into the given C++ type. A
-    :class:`cast_error` will be throw upon failure.
+Common member functions
+-----------------------
 
-.. function:: template <typename ... Args> object handle::call(Args&&... args) const
+.. doxygenclass:: object_api
+    :members:
 
-    Assuming the Python object is a function or implements the ``__call__``
-    protocol, ``call()`` invokes the underlying function, passing an arbitrary
-    set of parameters. The result is returned as a :class:`object` and may need
-    to be converted back into a Python object using :func:`handle::cast`.
+Without reference counting
+--------------------------
 
-    When some of the arguments cannot be converted to Python objects, the
-    function will throw a :class:`cast_error` exception. When the Python
-    function call fails, a :class:`error_already_set` exception is thrown.
+.. doxygenclass:: handle
+    :members:
 
 With reference counting
 -----------------------
 
-.. class:: object : public handle
-
-    Like :class:`handle`, the object class is a thin wrapper around an
-    arbitrary Python object (i.e. a ``PyObject *`` in Python's C API). In
-    contrast to :class:`handle`, it optionally increases the object's reference
-    count upon construction, and it *always* decreases the reference count when
-    the :class:`object` instance goes out of scope and is destructed. When
-    using :class:`object` instances consistently, it is much easier to get
-    reference counting right at the first attempt.
-
-.. function:: object::object(const object &o)
-
-    Copy constructor; always increases the reference count
-
-.. function:: object::object(const handle &h, bool borrowed)
-
-    Creates a :class:`object` from the given :class:`handle`. The reference
-    count is only increased if the ``borrowed`` parameter is set to ``true``.
-
-.. function:: object::object(PyObject *ptr, bool borrowed)
-
-    Creates a :class:`object` from the given raw Python object pointer. The
-    reference  count is only increased if the ``borrowed`` parameter is set to
-    ``true``.
-
-.. function:: object::object(object &&other)
-
-    Move constructor; steals the object from ``other`` and preserves its
-    reference count.
-
-.. function:: handle object::release()
+.. doxygenclass:: object
+    :members:
 
-    Resets the internal pointer to ``nullptr`` without without decreasing the
-    object's reference count. The function returns a raw handle to the original
-    Python object.
+.. doxygenfunction:: reinterpret_borrow
 
-.. function:: object::~object()
-
-    Destructor, which automatically calls :func:`handle::dec_ref()`.
+.. doxygenfunction:: reinterpret_steal
 
 Convenience classes for specific Python types
 =============================================
 
+.. doxygenclass:: module
+    :members:
 
-.. class:: module : public object
-
-.. function:: module::module(const char *name, const char *doc = nullptr)
-
-    Create a new top-level Python module with the given name and docstring
-
-.. function:: module module::def_submodule(const char *name, const char *doc = nullptr)
-
-    Create and return a new Python submodule with the given name and docstring.
-    This also works recursively, i.e.
-
-    .. code-block:: cpp
-
-        pybind11::module m("example", "pybind11 example plugin");
-        pybind11::module m2 = m.def_submodule("sub", "A submodule of 'example'");
-        pybind11::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
-
-.. cpp:function:: template <typename Func, typename ... Extra> module& module::def(const char *name, Func && f, Extra && ... extra)
-
-    Create Python binding for a new function within the module scope. ``Func``
-    can be a plain C++ function, a function pointer, or a lambda function. For
-    details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
+.. doxygengroup:: pytypes
+    :members:
 
 .. _extras:
 
-Passing extra arguments to the def function
-===========================================
-
-.. class:: arg
-
-.. function:: arg::arg(const char *name)
-
-.. function:: template <typename T> arg_v arg::operator=(T &&value)
-
-.. class:: arg_v : public arg
-
-    Represents a named argument with a default value
-
-.. class:: sibling
-
-    Used to specify a handle to an existing sibling function; used internally
-    to implement function overloading in :func:`module::def` and
-    :func:`class_::def`.
-
-.. function:: sibling::sibling(handle handle)
+Passing extra arguments to ``def`` or ``class_``
+================================================
 
-.. class doc
+.. doxygengroup:: annotations
+    :members:
 
-    This is class is internally used by pybind11.
+Python build-in functions
+=========================
 
-.. function:: doc::doc(const char *value)
+.. doxygengroup:: python_builtins
+    :members:
 
-    Create a new docstring with the specified value
+Exceptions
+==========
 
-.. class name
+.. doxygenclass:: error_already_set
+    :members:
 
-    This is class is internally used by pybind11.
+.. doxygenclass:: builtin_exception
+    :members:
 
-.. function:: name::name(const char *value)
 
-    Used to specify the function name
+Literals
+========
 
+.. doxygennamespace:: literals
diff --git a/ext/pybind11/docs/release.rst b/ext/pybind11/docs/release.rst
index a15504ea8..30d159a6f 100644
--- a/ext/pybind11/docs/release.rst
+++ b/ext/pybind11/docs/release.rst
@@ -1,8 +1,10 @@
 To release a new version of pybind11:
 
 - Update the version number and push to pypi
-    - Update ``pybind11/_version.py`` (set release version, remove 'dev')
-    - Update version in ``docs/conf.py``
+    - Update ``pybind11/_version.py`` (set release version, remove 'dev').
+    - Update ``PYBIND11_VERSION_MAJOR`` etc. in ``include/pybind11/common.h``.
+    - Ensure that all the information in ``setup.py`` is up-to-date.
+    - Update version in ``docs/conf.py``.
     - Tag release date in ``docs/changelog.rst``.
     - ``git add`` and ``git commit``.
     - if new minor version: ``git checkout -b vX.Y``, ``git push -u origin vX.Y``
diff --git a/ext/pybind11/docs/requirements.txt b/ext/pybind11/docs/requirements.txt
new file mode 100644
index 000000000..3818fe80e
--- /dev/null
+++ b/ext/pybind11/docs/requirements.txt
@@ -0,0 +1 @@
+breathe == 4.5.0