remainder of documentation

docs/basics.rst

@@ -80,14 +80,14 @@ a file named :file:`example.cpp` with the following contents:
 .. code-block:: cpp
 
     #include <pybind/pybind.h>
-    
+
     int add(int i, int j) {
         return i + j;
     }
 
     namespace py = pybind;
 
-    PYTHON_PLUGIN(example) {
+    PYBIND_PLUGIN(example) {
         py::module m("example", "pybind example plugin");
 
         m.def("add", &add, "A function which adds two numbers");
@@ -95,7 +95,7 @@ a file named :file:`example.cpp` with the following contents:
         return m.ptr();
     }
 
-The :func:`PYTHON_PLUGIN` macro creates a function that will be called when an
+The :func:`PYBIND_PLUGIN` macro creates a function that will be called when an
 ``import`` statement is issued from within Python. The next line creates a
 module named ``example`` (with the supplied docstring). The method
 :func:`module::def` generates binding code that exposes the
@@ -130,13 +130,14 @@ shows how to load and execute the example.
 
 .. code-block:: python
 
-    % python
+    $ python
     Python 2.7.10 (default, Aug 22 2015, 20:33:39)
     [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import example
     >>> example.add(1, 2)
     3L
+    >>>
 
 .. _keyword_args:
 
@@ -219,7 +220,7 @@ Supported data types
 
 The following basic data types are supported out of the box (some may require
 an additional extension header to be included). To pass other data structures
-as arguments and return values, refer to the section on :ref:`classes`.
+as arguments and return values, refer to the section on binding :ref:`classes`.
 
 +------------------------+--------------------------+---------------------+
 |  Data type             |  Description             | Header file         |

docs/classes.rst

@@ -24,10 +24,10 @@ The binding code for ``Pet`` looks as follows:
 .. code-block:: cpp
 
     #include <pybind/pybind.h>
-    
+
     namespace py = pybind;
 
-    PYTHON_PLUGIN(example) {
+    PYBIND_PLUGIN(example) {
         py::module m("example", "pybind example plugin");
 
         py::class_<Pet>(m, "Pet")
@@ -140,7 +140,8 @@ that can only be accessed via setters and getters.
 
 In this case, the method :func:`class_::def_property`
 (:func:`class_::def_property_readonly` for read-only data) can be used to
-provide an interface that is indistinguishable from within Python:
+provide a field-like interface within Python that will transparently call
+the setter and getter functions:
 
 .. code-block:: cpp
 
@@ -190,7 +191,7 @@ class.
 
 Instances then expose fields and methods of both types:
 
-.. code-block:: python 
+.. code-block:: python
 
     >>> p = example.Dog('Molly')
     >>> p.name
@@ -249,13 +250,18 @@ The overload signatures are also visible in the method's docstring:
      |      2. Signature : (Pet, str) -> None
      |
      |      Set the pet's name
-     |
+
+.. note::
+
+    To define multiple overloaded constructors, simply declare one after the
+    other using the ``.def(py::init<...>())`` syntax. The existing machinery
+    for specifying keyword and default arguments also works.
 
 Enumerations and internal types
 ===============================
 
-Let's now suppose that the example class also contains an internal enumeration
-type.
+Let's now suppose that the example class contains an internal enumeration type,
+e.g.:
 
 .. code-block:: cpp
 
@@ -288,9 +294,9 @@ The binding code for this example looks as follows:
 
 To ensure that the ``Kind`` type is created within the scope of ``Pet``, the
 ``pet`` :class:`class_` instance must be supplied to the :class:`enum_`.
-constructor. The :func:`enum_::export_values` function ensures that the enum
-entries are exported into the parent scope; skip this call for new C++11-style
-strongly typed enums.
+constructor. The :func:`enum_::export_values` function exports the enum entries
+into the parent scope, which should be skipped for newer C++11-style strongly
+typed enums.
 
 .. code-block:: python
 
@@ -301,4 +307,4 @@ strongly typed enums.
     1L
 
 
-.. [#f1] (those with an empty pair of brackets ``[]`` as the capture object) 
+.. [#f1] Stateless closures are those with an empty pair of brackets ``[]`` as the capture object.

docs/cmake.rst

@@ -78,7 +78,7 @@ and that the pybind11 repository is located in a subdirectory named :file:`pybin
       # into Blender or Maya later on, this will cause segfaults when multiple
       # conflicting Python instances are active at the same time.
 
-      # Windows is not affected by this issue since it handles DLL imports 
+      # Windows is not affected by this issue since it handles DLL imports
       # differently. The solution for Linux and Mac OS is simple: we just don't
       # link against the Python library. The resulting shared library will have
       # missing symbols, but that's perfectly fine -- they will be resolved at

docs/conf.py

@@ -116,6 +116,11 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    html_context = {
+        'css_files': [
+            '_static/theme_overrides.css',
+        ]
+    }
 
 #import alabaster
 

docs/intro.rst

@@ -4,7 +4,7 @@ About this project
 and vice versa, mainly to create Python bindings of existing C++ code. Its
 goals and syntax are similar to the excellent `Boost.Python`_ library by David
 Abrahams: to minimize boilerplate code in traditional extension modules by
-inferring type information using compile-time introspection. 
+inferring type information using compile-time introspection.
 
 .. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html
 
@@ -21,7 +21,9 @@ everything stripped away that isn't relevant for binding generation. The whole
 codebase requires less than 3000 lines of code and only depends 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 (tuples, lambda functions and
-variadic templates).
+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
 *************

docs/reference.rst

 .. _reference:
 
+.. warning::
+
+    Please be advised that the reference documentation discussing pybind11
+    internals is currently incomplete. Please refer to the previous sections
+    and the pybind header files for the nitty gritty details.
+
 Reference
 #########
 
 Macros
 ======
 
-.. function:: PYTHON_PLUGIN(const char *name)
+.. function:: PYBIND_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
@@ -15,7 +21,7 @@ Macros
 
     .. code-block:: cpp
 
-        PYTHON_PLUGIN(example) {
+        PYBIND_PLUGIN(example) {
             pybind::module m("example", "pybind example plugin");
             /// Set up bindings here
             return m.ptr();
@@ -37,7 +43,7 @@ Without reference counting
     various Python API functions.
 
 .. seealso::
-    
+
     The :class:`object` class inherits from :class:`handle` and adds automatic
     reference counting features.
 
@@ -122,7 +128,7 @@ Without reference counting
     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:`template <typename T> handle::cast`.
+    to be converted back into a Python object using :func:`handle::cast`.
 
     When some of the arguments cannot be converted to Python objects, the
     function will throw a :class:`cast_error` exception. When the Python
@@ -206,7 +212,7 @@ Passing extra arguments to the def function
 .. class:: template <typename T> arg_t<T> : public arg
 
     Represents a named argument with a default value
-    
+
 .. class:: sibling
 
     Used to specify a handle to an existing sibling function; used internally