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