remainder of documentation

docs/basics.rst

@@ -87,7 +87,7 @@ a file named :file:`example.cpp` with the following contents:
 
 
     namespace py = pybind;
     namespace py = pybind;
 
 
-    PYTHON_PLUGIN(example) {
+    PYBIND_PLUGIN(example) {
         py::module m("example", "pybind example plugin");
         py::module m("example", "pybind example plugin");
 
 
         m.def("add", &add, "A function which adds two numbers");
         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();
         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
 ``import`` statement is issued from within Python. The next line creates a
 module named ``example`` (with the supplied docstring). The method
 module named ``example`` (with the supplied docstring). The method
 :func:`module::def` generates binding code that exposes the
 :func:`module::def` generates binding code that exposes the
@@ -130,13 +130,14 @@ shows how to load and execute the example.
 
 
 .. code-block:: python
 .. code-block:: python
 
 
-    % python
+    $ python
     Python 2.7.10 (default, Aug 22 2015, 20:33:39)
     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
     [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.
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import example
     >>> import example
     >>> example.add(1, 2)
     >>> example.add(1, 2)
     3L
     3L
+    >>>
 
 
 .. _keyword_args:
 .. _keyword_args:
 
 
@@ -219,7 +220,7 @@ Supported data types
 
 
 The following basic data types are supported out of the box (some may require
 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
 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         |
 |  Data type             |  Description             | Header file         |

docs/classes.rst

@@ -27,7 +27,7 @@ The binding code for ``Pet`` looks as follows:
 
 
     namespace py = pybind;
     namespace py = pybind;
 
 
-    PYTHON_PLUGIN(example) {
+    PYBIND_PLUGIN(example) {
         py::module m("example", "pybind example plugin");
         py::module m("example", "pybind example plugin");
 
 
         py::class_<Pet>(m, "Pet")
         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`
 In this case, the method :func:`class_::def_property`
 (:func:`class_::def_property_readonly` for read-only data) can be used to
 (: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
 .. code-block:: cpp
 
 
@@ -249,13 +250,18 @@ The overload signatures are also visible in the method's docstring:
      |      2. Signature : (Pet, str) -> None
      |      2. Signature : (Pet, str) -> None
      |
      |
      |      Set the pet's name
      |      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
 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
 .. 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
 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_`.
 ``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
 .. code-block:: python
 
 
@@ -301,4 +307,4 @@ strongly typed enums.
     1L
     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/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
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    html_context = {
+        'css_files': [
+            '_static/theme_overrides.css',
+        ]
+    }
 
 
 #import alabaster
 #import alabaster
 
 

docs/intro.rst

@@ -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
 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
 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
 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
 Core features
 *************
 *************

docs/reference.rst

 .. _reference:
 .. _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
 Reference
 #########
 #########
 
 
 Macros
 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
     This macro creates the entry point that will be invoked when the Python
     interpreter imports a plugin library. Please create a
     interpreter imports a plugin library. Please create a
@@ -15,7 +21,7 @@ Macros
 
 
     .. code-block:: cpp
     .. code-block:: cpp
 
 
-        PYTHON_PLUGIN(example) {
+        PYBIND_PLUGIN(example) {
             pybind::module m("example", "pybind example plugin");
             pybind::module m("example", "pybind example plugin");
             /// Set up bindings here
             /// Set up bindings here
             return m.ptr();
             return m.ptr();
@@ -122,7 +128,7 @@ Without reference counting
     Assuming the Python object is a function or implements the ``__call__``
     Assuming the Python object is a function or implements the ``__call__``
     protocol, ``call()`` invokes the underlying function, passing an arbitrary
     protocol, ``call()`` invokes the underlying function, passing an arbitrary
     set of parameters. The result is returned as a :class:`object` and may need
     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
     When some of the arguments cannot be converted to Python objects, the
     function will throw a :class:`cast_error` exception. When the Python
     function will throw a :class:`cast_error` exception. When the Python