took a stab at some documentation
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..511b47c
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,192 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = .build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " applehelp to make an Apple Help Book"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " coverage to run coverage check of the documentation (if enabled)"
+
+clean:
+ rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pybind11.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pybind11.qhc"
+
+applehelp:
+ $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+ @echo
+ @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+ @echo "N.B. You won't be able to view it unless you put it in" \
+ "~/Library/Documentation/Help or install it in your application" \
+ "bundle."
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/pybind11"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pybind11"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+ $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+ @echo "Testing of coverage in the sources finished, look at the " \
+ "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/docs/advanced.rst b/docs/advanced.rst
new file mode 100644
index 0000000..6b7cc1e
--- /dev/null
+++ b/docs/advanced.rst
@@ -0,0 +1,202 @@
+.. _advanced:
+
+Advanced topics
+###############
+
+Operator overloading
+====================
+
+Overriding virtual functions in Python
+======================================
+
+Passing anonymous functions
+===========================
+
+Return value policies
+=====================
+
+Functions taking Python objects as arguments
+============================================
+
+Callbacks
+=========
+
+Buffer protocol
+===============
+
+Python supports an extremely general and convenient approach for exchanging
+data between plugin libraries. Types can expose a buffer view which provides
+fast direct access to the raw internal representation. Suppose we want to bind
+the following simplistic Matrix class:
+
+.. code-block:: cpp
+
+ class Matrix {
+ public:
+ Matrix(size_t rows, size_t cols) : m_rows(rows), m_cols(cols) {
+ m_data = new float[rows*cols];
+ }
+ float *data() { return m_data; }
+ size_t rows() const { return m_rows; }
+ size_t cols() const { return m_cols; }
+ private:
+ size_t m_rows, m_cols;
+ float *m_data;
+ };
+
+The following binding code exposes the ``Matrix`` contents as a buffer object,
+making it possible to cast Matrixes into NumPy arrays. It is even possible to
+completely avoid copy operations with Python expressions like
+``np.array(matrix_instance, copy = False)``.
+
+.. code-block:: cpp
+
+ py::class_<Matrix>(m, "Matrix")
+ .def_buffer([](Matrix &m) -> py::buffer_info {
+ return py::buffer_info(
+ m.data(), /* Pointer to buffer */
+ sizeof(float), /* Size of one scalar */
+ py::format_descriptor<float>::value(), /* Python struct-style format descriptor */
+ 2, /* Number of dimensions */
+ { m.rows(), m.cols() }, /* Buffer dimensions */
+ { sizeof(float) * m.rows(), /* Strides (in bytes) for each index */
+ sizeof(float) }
+ );
+ });
+
+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.
+
+.. code-block:: cpp
+
+ struct buffer_info {
+ void *ptr;
+ size_t itemsize;
+ std::string format;
+ int ndim;
+ std::vector<size_t> shape;
+ std::vector<size_t> strides;
+ };
+
+To create a C++ function that can take a Python buffer object as an argument,
+simply use the type ``py::buffer`` as one of its arguments. Buffers can exist
+in a great variety of configurations, hence some safety checks are usually
+necessary in the function body. Below, you can see an basic example on how to
+define a custom constructor for the Eigen double precision matrix
+(``Eigen::MatrixXd``) type, which supports initialization from compatible
+buffer
+objects (e.g. a NumPy matrix).
+
+.. code-block:: cpp
+
+ py::class_<Eigen::MatrixXd>(m, "MatrixXd")
+ .def("__init__", [](Eigen::MatrixXd &m, py::buffer b) {
+ /* Request a buffer descriptor from Python */
+ py::buffer_info info = b.request();
+
+ /* Some sanity checks ... */
+ if (info.format != py::format_descriptor<double>::value())
+ throw std::runtime_error("Incompatible format: expected a double array!");
+
+ if (info.ndim != 2)
+ throw std::runtime_error("Incompatible buffer dimension!");
+
+ if (info.strides[0] == sizeof(double)) {
+ /* Buffer has the right layout -- directly copy. */
+ new (&m) Eigen::MatrixXd(info.shape[0], info.shape[1]);
+ memcpy(m.data(), info.ptr, sizeof(double) * m.size());
+ } else {
+ /* Oops -- the buffer is transposed */
+ new (&m) Eigen::MatrixXd(info.shape[1], info.shape[0]);
+ memcpy(m.data(), info.ptr, sizeof(double) * m.size());
+ m.transposeInPlace();
+ }
+ });
+
+NumPy support
+=============
+
+By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can
+restrict the function so that it only accepts NumPy arrays (rather than any
+type of Python object satisfying the buffer object protocol).
+
+In many situations, we want to define a function which only accepts a NumPy
+array of a certain data type. This is possible via the ``py::array_dtype<T>``
+template. For instance, the following function requires the argument to be a
+dense array of doubles in C-style ordering.
+
+.. code-block:: cpp
+
+ void f(py::array_dtype<double> array);
+
+When it is invoked with a different type (e.g. an integer), the binding code
+will attempt to cast the input into a NumPy array of the requested type.
+Note that this feature requires the ``pybind/numpy.h`` header to be included.
+
+Vectorizing functions
+=====================
+
+Suppose we want to bind a function with the following signature to Python so
+that it can process arbitrary NumPy array arguments (vectors, matrices, general
+N-D arrays) in addition to its normal arguments:
+
+.. code-block:: cpp
+
+ double my_func(int x, float y, double z);
+
+After including the ``pybind/numpy.h`` header, this is extremely simple:
+
+.. code-block:: cpp
+
+ m.def("vectorized_func", py::vectorize(my_func));
+
+Invoking the function like below causes 4 calls to be made to ``my_func`` with
+each of the the array elements. The result is returned as a NumPy array of type
+``numpy.dtype.float64``.
+
+.. code-block:: python
+
+ >>> x = np.array([[1, 3],[5, 7]])
+ >>> y = np.array([[2, 4],[6, 8]])
+ >>> z = 3
+ >>> result = vectorized_func(x, y, z)
+
+The scalar argument ``z`` is transparently replicated 4 times. The input
+arrays ``x`` and ``y`` are automatically converted into the right types (they
+are of type ``numpy.dtype.int64`` but need to be ``numpy.dtype.int32`` and
+``numpy.dtype.float32``, respectively)
+
+Sometimes we might want to explitly exclude an argument from the vectorization
+because it makes little sense to wrap it in a NumPy array. For instance,
+suppose the function signature was
+
+.. code-block:: cpp
+
+ double my_func(int x, float y, my_custom_type *z);
+
+This can be done with a stateful Lambda closure:
+
+.. code-block:: cpp
+
+ // Vectorize a lambda function with a capture object (e.g. to exclude some arguments from the vectorization)
+ m.def("vectorized_func",
+ [](py::array_dtype<int> x, py::array_dtype<float> y, my_custom_type *z) {
+ auto stateful_closure = [z](int x, float y) { return my_func(x, y, z); };
+ return py::vectorize(stateful_closure)(x, y);
+ }
+ );
+
+Throwing exceptions
+===================
+
+STL data structures
+===================
+
+Smart pointers
+==============
+
+.. _custom_constructors:
+
+Custom constructors
+===================
diff --git a/docs/basics.rst b/docs/basics.rst
new file mode 100644
index 0000000..eb37da5
--- /dev/null
+++ b/docs/basics.rst
@@ -0,0 +1,263 @@
+.. _basics:
+
+First steps
+###########
+
+This sections demonstrates the basic features of pybind11. Before getting
+started, make sure that development environment is set up to compile the
+included set of examples, which also double as test cases.
+
+
+Compiling the test cases
+========================
+
+Linux/MacOS
+-----------
+
+On Linux you'll need to install the **python-dev** or **python3-dev** packages as
+well as **cmake**. On Mac OS, the included python version works out of the box,
+but **cmake** must still be installed.
+
+After installing the prerequisites, run
+
+.. code-block:: bash
+
+ cmake .
+ make -j 4
+
+followed by
+
+.. code-block:: bash
+
+ make test
+
+Windows
+-------
+
+On Windows, use the `CMake GUI`_ to create a Visual Studio project. Note that
+only the 2015 release and newer versions are supported since pybind11 relies on
+various C++11 language features that break older versions of Visual Studio.
+After running CMake, open the created :file:`pybind.sln` file and perform a
+release build, which will will produce a file named
+:file:`Release\\example.pyd`. Copy this file to the :file:`example` directory
+and run :file:`example\\run_test.py` using the targeted Python version.
+
+.. _`CMake GUI`: https://cmake.org/runningcmake
+
+.. Note::
+
+ When all tests fail, make sure that
+
+ 1. The Python binary and the testcases are compiled for the same processor
+ type and bitness (i.e. either **i386** or **x86_64**)
+
+ 2. The Python binary used to run :file:`example\\run_test.py` matches the
+ Python version specified in the CMake GUI. This is controlled via
+ the ``PYTHON_EXECUTABLE`` ``PYTHON_INCLUDE_DIR``, and
+ ``PYTHON_LIBRARY`` variables.
+
+.. seealso::
+
+ Advanced users who are already familiar with Boost.Python may want to skip
+ the tutorial and look at the test cases in the :file:`example` directory,
+ which exercise all features of pybind11.
+
+Creating bindings for a simple function
+=======================================
+
+Let's start by creating Python bindings for an extremely simple function, which
+adds two numbers and returns their result:
+
+.. code-block:: cpp
+
+ int add(int i, int j) {
+ return i + j;
+ }
+
+For simplicity [#f1]_, we'll put both this function and the binding code into
+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) {
+ py::module m("example", "pybind example plugin");
+
+ m.def("add", &add, "A function which adds two numbers");
+
+ return m.ptr();
+ }
+
+The :func:`PYTHON_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
+``add()`` function to Python. The last line returns the internal Python object
+associated with ``m`` to the Python interpreter.
+
+.. note::
+
+ Notice how little code was needed to expose our function to Python: all
+ details regarding the function's parameters and return value were
+ automatically inferred using template metaprogramming. This overall
+ approach and the used syntax are borrowed from Boost.Python, though the
+ underlying implementation is very different.
+
+pybind11 is a header-only-library, hence it is not necessary to link against
+any special libraries (other than Python itself). On Windows, use the CMake
+build file discussed in section :ref:`cmake`. On Linux and Mac OS, the above
+example can be compiled using the following command
+
+.. code-block:: bash
+
+ $ c++ -O3 -shared -std=c++11 -I <path-to-pybind>/include `python-config --cflags --libs` example.cpp -o example.so
+
+In general, it is advisable to include several additional build parameters
+that can considerably reduce the size of the created binary. Refer to section
+:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based
+build system.
+
+Assuming that the created file :file:`example.so` (:file:`example.pyd` on Windows)
+is located in the current directory, the following interactive Python session
+shows how to load and execute the example.
+
+.. code-block:: 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:
+
+Keyword arguments
+=================
+
+With a simple modification code, it is possible to inform Python about the
+names of the arguments ("i" and "j" in this case).
+
+.. code-block:: cpp
+
+ m.def("add", &add, "A function which adds two numbers",
+ py::arg("i"), py::arg("j"));
+
+:class:`arg` is one of several special tag classes which can be used to pass
+metadata into :func:`module::def`. With this modified binding code, we can now
+call the function using keyword arguments, which is a more readable alternative
+particularly for functions taking many parameters:
+
+.. code-block:: python
+
+ >>> import example
+ >>> example.add(i=1, j=2)
+ 3L
+
+The keyword names also appear in the function signatures within the documentation.
+
+.. code-block:: python
+
+ >>> help(example)
+
+ ....
+
+ FUNCTIONS
+ add(...)
+ Signature : (i: int32_t, j: int32_t) -> int32_t
+
+ A function which adds two numbers
+
+.. _default_args:
+
+Default arguments
+=================
+
+Suppose now that the function to be bound has default arguments, e.g.:
+
+.. code-block:: cpp
+
+ int add(int i = 1, int j = 2) {
+ return i + j;
+ }
+
+Unfortunately, pybind11 cannot automatically extract these parameters, since they
+are not part of the function's type information. However, they are simple to specify
+using an extension of :class:`arg`:
+
+.. code-block:: cpp
+
+ m.def("add", &add, "A function which adds two numbers",
+ py::arg("i") = 1, py::arg("j") = 2);
+
+The default values also appear within the documentation.
+
+.. code-block:: python
+
+ >>> help(example)
+
+ ....
+
+ FUNCTIONS
+ add(...)
+ Signature : (i: int32_t = 1L, j: int32_t = 2L) -> int32_t
+
+ A function which adds two numbers
+
+.. _supported_types:
+
+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`.
+
++------------------------+--------------------------+---------------------+
+| Data type | Description | Header file |
++========================+==========================+=====================+
+| int8_t, uint8_t | 8-bit integers | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| int16_t, uint16_t | 16-bit integers | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| int32_t, uint32_t | 32-bit integers | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| int64_t, uint64_t | 64-bit integers | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| ssize_t, size_t | Platform-dependent size | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| float, double | Floating point types | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| bool | Two-state Boolean type | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| char | Character literal | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| const char * | UTF-8 string literal | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| std::string | STL dynamic UTF-8 string | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| std::pair<T1, T2> | Pair of two custom types | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| std::tuple<....> | Arbitrary tuple of types | pybind/pybind.h |
++------------------------+--------------------------+---------------------+
+| std::complex<T> | Complex numbers | pybind/complex.h |
++------------------------+--------------------------+---------------------+
+| std::vector<T> | STL dynamic array | pybind/stl.h |
++------------------------+--------------------------+---------------------+
+| std::map<T1, T2> | STL dynamic maps | pybind/stl.h |
++------------------------+--------------------------+---------------------+
+| std::function<...> | STL polymorphic function | pybind/functional.h |
++------------------------+--------------------------+---------------------+
+
+
+.. [#f1] In practice, implementation and binding code will generally be located
+ in separate files.
+
diff --git a/docs/classes.rst b/docs/classes.rst
new file mode 100644
index 0000000..c141c16
--- /dev/null
+++ b/docs/classes.rst
@@ -0,0 +1,304 @@
+.. _classes:
+
+Object-oriented code
+####################
+
+Creating bindings for a custom type
+===================================
+
+Let's now look at a more complex example where we'll create bindings for a
+custom C++ data structure named ``Pet``. Its definition is given below:
+
+.. code-block:: cpp
+
+ struct Pet {
+ Pet(const std::string &name) : name(name) { }
+ void setName(const std::string &name_) { name = name_; }
+ const std::string &getName() const { return name; }
+
+ std::string name;
+ };
+
+The binding code for ``Pet`` looks as follows:
+
+.. code-block:: cpp
+
+ #include <pybind/pybind.h>
+
+ namespace py = pybind;
+
+ PYTHON_PLUGIN(example) {
+ py::module m("example", "pybind example plugin");
+
+ py::class_<Pet>(m, "Pet")
+ .def(py::init<const std::string &>())
+ .def("setName", &Pet::setName)
+ .def("getName", &Pet::getName);
+
+ return m.ptr();
+ }
+
+: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
+interactive Python session demonstrating this example is shown below:
+
+.. code-block:: python
+
+ % python
+ >>> import example
+ >>> p = example.Pet('Molly')
+ >>> print(p)
+ <example.Pet object at 0x10cd98060>
+ >>> p.getName()
+ u'Molly'
+ >>> p.setName('Charly')
+ >>> p.getName()
+ u'Charly'
+
+Keyword and default arguments
+=============================
+It is possible to specify keyword and default arguments using the syntax
+discussed in the previous chapter. Refer to the sections :ref:`keyword_args`
+and :ref:`default_args` for details.
+
+Binding lambda functions
+========================
+
+Note how ``print(p)`` produced a rather useless summary of our data structure in the example above:
+
+.. code-block:: python
+
+ >>> print(p)
+ <example.Pet object at 0x10cd98060>
+
+To address this, we could bind an utility function that returns a human-readable
+summary to the special method slot named ``__repr__``. Unfortunately, there is no
+suitable functionality in the ``Pet`` data structure, and it would be nice if
+we did not have to change it. This can easily be accomplished by binding a
+Lambda function instead:
+
+.. code-block:: cpp
+
+ py::class_<Pet>(m, "Pet")
+ .def(py::init<const std::string &>())
+ .def("setName", &Pet::setName)
+ .def("getName", &Pet::getName)
+ .def("__repr__",
+ [](const Pet &a) {
+ return "<example.Pet named '" + a.name + "'>";
+ }
+ );
+
+Both stateless [#f1]_ and stateful lambda closures are supported by pybind11.
+With the above change, the same Python code now produces the following output:
+
+.. code-block:: python
+
+ >>> print(p)
+ <example.Pet named 'Molly'>
+
+Instance and static fields
+==========================
+
+We can also directly expose the ``name`` field using the
+:func:`class_::def_readwrite` method. A similar :func:`class_::def_readonly`
+method also exists for ``const`` fields.
+
+.. code-block:: cpp
+
+ py::class_<Pet>(m, "Pet")
+ .def(py::init<const std::string &>())
+ .def_readwrite("name", &Pet::name)
+ // ... remainder ...
+
+This makes it possible to write
+
+.. code-block:: python
+
+ >>> p = example.Pet('Molly')
+ >>> p.name
+ u'Molly'
+ >>> p.name = 'Charly'
+ >>> p.name
+ u'Charly'
+
+Now suppose that ``Pet::name`` was a private internal variable
+that can only be accessed via setters and getters.
+
+.. code-block:: cpp
+
+ class Pet {
+ public:
+ Pet(const std::string &name) : name(name) { }
+ void setName(const std::string &name_) { name = name_; }
+ const std::string &getName() const { return name; }
+ private:
+ std::string name;
+ };
+
+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:
+
+.. code-block:: cpp
+
+ py::class_<Pet>(m, "Pet")
+ .def(py::init<const std::string &>())
+ .def_property("name", &Pet::getName, &Pet::setName)
+ // ... remainder ...
+
+.. seealso::
+
+ Similar functions :func:`class_::def_readwrite_static`,
+ :func:`class_::def_readonly_static` :func:`class_::def_property_static`,
+ and :func:`class_::def_property_readonly_static` are provided for binding
+ static variables and properties.
+
+Inheritance
+===========
+
+Suppose now that the example consists of two data structures with an
+inheritance relationship:
+
+.. code-block:: cpp
+
+ struct Pet {
+ Pet(const std::string &name) : name(name) { }
+ std::string name;
+ };
+
+ struct Dog : Pet {
+ Dog(const std::string &name) : Pet(name) { }
+ std::string bark() const { return "woof!"; }
+ };
+
+To capture the hierarchical relationship in pybind11, we must assign a name to
+the ``Pet`` :class:`class_` instance and reference it when binding the ``Dog``
+class.
+
+.. code-block:: cpp
+
+ py::class_<Pet> pet(m, "Pet");
+ pet.def(py::init<const std::string &>())
+ .def_readwrite("name", &Pet::name);
+
+ py::class_<Dog>(m, "Dog", pet /* <- specify parent */)
+ .def(py::init<const std::string &>())
+ .def("bark", &Dog::bark);
+
+Instances then expose fields and methods of both types:
+
+.. code-block:: python
+
+ >>> p = example.Dog('Molly')
+ >>> p.name
+ u'Molly'
+ >>> p.bark()
+ u'woof!'
+
+Overloaded methods
+==================
+
+Sometimes there are several overloaded C++ methods with the same name taking
+different kinds of input arguments:
+
+.. code-block:: cpp
+
+ 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; }
+
+ std::string name;
+ int age;
+ };
+
+Attempting to bind ``Pet::set`` will cause an error since the compiler does not
+know which method the user intended to select. We can disambiguate by casting
+them to function pointers. Binding multiple functions to the same Python name
+automatically creates a chain of fucnction overloads that will be tried in
+sequence.
+
+.. code-block:: cpp
+
+ py::class_<Pet>(m, "Pet")
+ .def(py::init<const std::string &, int>())
+ .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age")
+ .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name");
+
+The overload signatures are also visible in the method's docstring:
+
+.. code-block:: python
+
+ >>> help(example.Pet)
+
+ class Pet(__builtin__.object)
+ | Methods defined here:
+ |
+ | __init__(...)
+ | Signature : (Pet, str, int32_t) -> None
+ |
+ | set(...)
+ | 1. Signature : (Pet, int32_t) -> None
+ |
+ | Set the pet's age
+ |
+ | 2. Signature : (Pet, str) -> None
+ |
+ | Set the pet's name
+ |
+
+Enumerations and internal types
+===============================
+
+Let's now suppose that the example class also contains an internal enumeration
+type.
+
+.. code-block:: cpp
+
+ struct Pet {
+ enum Kind {
+ Dog = 0,
+ Cat
+ };
+
+ Pet(const std::string &name, Kind type) : name(name), type(type) { }
+
+ std::string name;
+ Kind type;
+ };
+
+The binding code for this example looks as follows:
+
+.. code-block:: cpp
+
+ py::class_<Pet> pet(m, "Pet");
+
+ pet.def(py::init<const std::string &, Pet::Kind>())
+ .def_readwrite("name", &Pet::name)
+ .def_readwrite("type", &Pet::type);
+
+ py::enum_<Pet::Kind>(pet, "Kind")
+ .value("Dog", Pet::Kind::Dog)
+ .value("Cat", Pet::Kind::Cat)
+ .export_values();
+
+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.
+
+.. code-block:: python
+
+ >>> p = Pet('Lucy', Pet.Cat)
+ >>> p.type
+ Kind.Cat
+ >>> int(p.type)
+ 1L
+
+
+.. [#f1] (those with an empty pair of brackets ``[]`` as the capture object)
diff --git a/docs/cmake.rst b/docs/cmake.rst
new file mode 100644
index 0000000..a5d0740
--- /dev/null
+++ b/docs/cmake.rst
@@ -0,0 +1,102 @@
+.. _cmake:
+
+Building with CMake
+===================
+
+The following snippet should be a good starting point to create bindings across
+platforms. It assumes that the code is located in a file named :file:`example.cpp`,
+and that the pybind11 repository is located in a subdirectory named :file:`pybind11`.
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 2.8)
+
+ project(example)
+
+ # Add a CMake parameter for choosing a desired Python version
+ set(EXAMPLE_PYTHON_VERSION "" CACHE STRING "Python version to use for compiling the example library")
+
+ # Set a default build configuration if none is specified. 'MinSizeRel' produces the smallest binaries
+ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+ message(STATUS "Setting build type to 'MinSizeRel' as none was specified.")
+ set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE)
+ set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release"
+ "MinSizeRel" "RelWithDebInfo")
+ endif()
+ string(TOUPPER "${CMAKE_BUILD_TYPE}" U_CMAKE_BUILD_TYPE)
+
+ # Try to autodetect Python (can be overridden manually if needed)
+ set(Python_ADDITIONAL_VERSIONS 3.4 3.5 3.6)
+ find_package(PythonLibs ${EXAMPLE_PYTHON_VERSION} REQUIRED)
+
+ if (UNIX)
+ # Enable C++11 mode
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+
+ # Enable link time optimization and set the default symbol
+ # visibility to hidden (very important to obtain small binaries)
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=hidden -flto")
+ endif()
+ endif()
+
+ # Include path for Python header files
+ include_directories(${PYTHON_INCLUDE_DIR})
+
+ # Include path for pybind11 header files -- this may need to be changed depending on your setup
+ include_directories(${PROJECT_SOURCE_DIR}/pybind11/include)
+
+ # Create the binding library
+ add_library(example SHARED
+ example.cpp
+ # ... extra files go here ...
+ )
+
+ # Don't add a 'lib' prefix to the shared library
+ set_target_properties(example PROPERTIES PREFIX "")
+
+ if (WIN32)
+ if (MSVC)
+ # Enforce size-based optimization and link time code generation
+ # on MSVC (~30% smaller binaries in experiments). /bigobj is needed
+ # for bigger binding projects due to the limit to 64k addressable sections
+ # /MP enables multithreaded builds (relevant when there are many files).
+ set_target_properties(example PROPERTIES COMPILE_FLAGS "/Os /GL /MP /bigobj")
+ set_target_properties(example PROPERTIES LINK_FLAGS "/LTCG")
+ endif()
+
+ # .PYD file extension on Windows
+ set_target_properties(example PROPERTIES SUFFIX ".pyd")
+
+ # Link against the Python shared library
+ target_link_libraries(example ${PYTHON_LIBRARY})
+ elseif (UNIX)
+ # It's quite common to have multiple copies of the same Python version
+ # installed on one's system. E.g.: one copy from the OS and another copy
+ # that's statically linked into an application like Blender or Maya.
+ # If we link our plugin library against the OS Python here and import it
+ # 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
+ # 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
+ # import time.
+
+ # .SO file extension on Linux/Mac OS
+ set_target_properties(example PROPERTIES SUFFIX ".so")
+
+ # Strip unnecessary sections of the binary on Linux/Mac OS
+ if(APPLE)
+ set_target_properties(example PROPERTIES MACOSX_RPATH ".")
+ set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup -dead_strip")
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ add_custom_command(TARGET example POST_BUILD COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so)
+ endif()
+ else()
+ if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
+ add_custom_command(TARGET example POST_BUILD COMMAND strip ${PROJECT_BINARY_DIR}/example.so)
+ endif()
+ endif()
+ endif()
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..f883fef
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# pybind11 documentation build configuration file, created by
+# sphinx-quickstart on Sun Oct 11 19:23:48 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'pybind11'
+copyright = '2015, Wenzel Jakob'
+author = 'Wenzel Jakob'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['.build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+#pygments_style = 'monokai'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+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()]
+
+#import alabaster
+
+#html_theme_path = [alabaster.get_path()]
+#extensions = ['alabaster']
+#html_theme = 'alabaster'
+#html_sidebars = {
+ #'**': [
+ #'about.html',
+ #'navigation.html',
+ #'relations.html',
+ #'searchbox.html'
+ #]
+#}
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pybind11doc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'pybind11.tex', 'pybind11 Documentation',
+ 'Wenzel Jakob', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'pybind11', 'pybind11 Documentation',
+ [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'pybind11', 'pybind11 Documentation',
+ author, 'pybind11', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+primary_domain = 'cpp'
+highlight_language = 'cpp'
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..253c2c2
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,15 @@
+Welcome to pybind11's documentation!
+====================================
+
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ basics
+ classes
+ advanced
+ cmake
+ reference
diff --git a/docs/intro.rst b/docs/intro.rst
new file mode 100644
index 0000000..3fa3626
--- /dev/null
+++ b/docs/intro.rst
@@ -0,0 +1,62 @@
+About this project
+==================
+**pybind11** is a lightweight header library that exposes C++ types in Python
+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.
+
+.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html
+
+The main issue with Boost.Python—and the reason for creating such a similar
+project—is Boost. Boost is an enormously large and complex suite of utility
+libraries that works with almost every C++ compiler in existence. This
+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. 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).
+
+Core features
+*************
+The following core C++ features can be mapped to Python
+
+- Functions accepting and returning custom data structures per value, reference, or pointer
+- Instance methods and static methods
+- Overloaded functions
+- Instance attributes and static attributes
+- Exceptions
+- Enumerations
+- Callbacks
+- Custom operators
+- STL data structures
+- Smart pointers with reference counting like ``std::shared_ptr``
+- Internal references with correct reference counting
+- C++ classes with virtual (and pure virtual) methods can be extended in Python
+
+Goodies
+*******
+In addition to the core functionality, pybind11 provides some extra goodies:
+
+- It is possible to bind C++11 lambda functions with captured variables. The
+ lambda capture data is stored inside the resulting Python function object.
+
+- pybind11 uses C++11 move constructors and move assignment operators whenever
+ possible to efficiently transfer custom data types.
+
+- It's easy to expose the internal storage of custom data types through
+ Pythons' buffer protocols. This is handy e.g. for fast conversion between
+ C++ matrix classes like Eigen and NumPy without expensive copy operations.
+
+- pybind11 can automatically vectorize functions so that they are transparently
+ applied to all entries of one or more NumPy array arguments.
+
+- Python's slice-based access and assignment operations can be supported with
+ just a few lines of code.
+
diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..8fbb396
--- /dev/null
+++ b/docs/reference.rst
@@ -0,0 +1,232 @@
+.. _reference:
+
+Reference
+#########
+
+Macros
+======
+
+.. function:: PYTHON_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
+
+ PYTHON_PLUGIN(example) {
+ pybind::module m("example", "pybind example plugin");
+ /// Set up bindings here
+ return m.ptr();
+ }
+
+.. _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()
+
+ Return the ``PyObject *`` underlying a :class:`handle`.
+
+.. function:: void handle::inc_ref()
+
+ 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.
+
+.. function:: void handle::dec_ref()
+
+ 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.
+
+.. function:: void handle::ref_count()
+
+ Return the object's current reference count
+
+.. function:: handle handle::get_type()
+
+ Return a handle to the Python type object underlying the instance
+
+.. function detail::accessor handle::operator[](handle key)
+
+ 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)
+
+ See the above function (the only difference is that they key is provided as
+ a string literal).
+
+.. function detail::accessor handle::attr(handle key)
+
+ 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)
+
+ 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()
+
+ Attempt to cast the Python object into the given C++ type. A
+ :class:`cast_error` will be throw upon failure.
+
+.. function:: template <typename ... Args> object handle::call(Args&&... args)
+
+ 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`.
+
+ 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.
+
+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:: object::~object()
+
+ Constructor, which automatically calls :func:`handle::dec_ref()`.
+
+Convenience classes for specific Python types
+=============================================
+
+
+.. 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
+
+ pybind::module m("example", "pybind example plugin");
+ pybind::module m2 = m.def_submodule("sub", "A submodule of 'example'");
+ pybind::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`.
+
+.. _extras:
+
+Passing extra arguments to the def function
+===========================================
+
+.. class:: arg
+
+.. function:: arg::arg(const char *name)
+
+.. function:: template <typename T> arg_t<T> arg::operator=(const T &value)
+
+.. 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
+ to implement function overloading in :func:`module::def` and
+ :func:`class_::def`.
+
+.. function:: sibling::sibling(handle handle)
+
+.. class doc
+
+ This is class is internally used by pybind11.
+
+.. function:: doc::doc(const char *value)
+
+ Create a new docstring with the specified value
+
+.. class name
+
+ This is class is internally used by pybind11.
+
+.. function:: name::name(const char *value)
+
+ Used to specify the function name