diff --git a/docs/advanced.rst b/docs/advanced.rst
index 2b78c7e80..e3bf6c777 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -102,7 +102,7 @@ C++ side, or to perform other types of customization.
 
 .. seealso::
 
-    The file :file:`example/example-operator-overloading.cpp` contains a
+    The file :file:`tests/test_operator_overloading.cpp` contains a
     complete example that demonstrates how to work with overloaded operators in
     more detail.
 
@@ -203,14 +203,14 @@ The following interactive session shows how to call them from Python.
     is passed as an argument to another C++ function exposed in Python. In this
     case, there is no overhead. Pybind11 will extract the underlying C++
     function pointer from the wrapped function to sidestep a potential C++ ->
-    Python -> C++ roundtrip. This is demonstrated in Example 5.
+    Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`.
 
 .. note::
 
     This functionality is very useful when generating bindings for callbacks in
     C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).
 
-    The file :file:`example/example-callbacks.cpp` contains a complete example
+    The file :file:`tests/test_callbacks.cpp` contains a complete example
     that demonstrates how to work with callbacks and anonymous functions in
     more detail.
 
@@ -354,7 +354,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example-virtual-functions.cpp` contains a complete
+    The file :file:`tests/test_virtual_functions.cpp` contains a complete
     example that demonstrates how to override virtual functions using pybind11
     in more detail.
 
@@ -472,7 +472,7 @@ can now create a python class that inherits from ``Dog``:
 
 .. seealso::
 
-    See the file :file:`example-virtual-functions.cpp` for complete examples
+    See the file :file:`tests/test_virtual_functions.cpp` for complete examples
     using both the duplication and templated trampoline approaches.
 
 .. _macro_notes:
@@ -556,7 +556,7 @@ out of the box with just the core :file:`pybind11/pybind11.h` header.
 
 .. seealso::
 
-    The file :file:`example/example-python-types.cpp` contains a complete
+    The file :file:`tests/test_python_types.cpp` contains a complete
     example that demonstrates how to pass STL data types in more detail.
 
 Binding sequence data types, iterators, the slicing protocol, etc.
@@ -566,7 +566,7 @@ Please refer to the supplemental example for details.
 
 .. seealso::
 
-    The file :file:`example/example-sequences-and-iterators.cpp` contains a
+    The file :file:`tests/test_sequences_and_iterators.cpp` contains a
     complete example that shows how to bind a sequence data type, including
     length queries (``__len__``), iterators (``__iter__``), the slicing
     protocol and other kinds of useful operations.
@@ -690,7 +690,7 @@ container:
 
 .. seealso::
 
-    The file :file:`example/example-keep-alive.cpp` contains a complete example
+    The file :file:`tests/test_keep_alive.cpp` contains a complete example
     that demonstrates using :class:`keep_alive` in more detail.
 
 Implicit type conversions
@@ -892,7 +892,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example-smart-ptr.cpp` contains a complete example
+    The file :file:`tests/test_smart_ptr.cpp` contains a complete example
     that demonstrates how to work with custom reference-counting holder types
     in more detail.
 
@@ -1005,7 +1005,7 @@ a first shot at handling the exception).
 Inside the translator, ``std::rethrow_exception`` should be used within
 a try block to re-throw the exception. A catch clause can then use
 ``PyErr_SetString`` to set a Python exception as demonstrated
-in :file:`example-custom-exceptions.cpp``.
+in :file:`tests/test_exceptions.cpp`.
 
 This example also demonstrates how to create custom exception types
 with ``py::exception``.
@@ -1143,7 +1143,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example-opaque-types.cpp` contains a complete
+    The file :file:`tests/test_opaque_types.cpp` contains a complete
     example that demonstrates how to create and expose opaque types using
     pybind11 in more detail.
 
@@ -1198,7 +1198,7 @@ with NumPy and SciPy.
 
 .. seealso::
 
-    The file :file:`example/eigen.cpp` contains a complete example that
+    The file :file:`tests/test_eigen.cpp` contains a complete example that
     shows how to pass Eigen sparse and dense data types in more detail.
 
 Buffer protocol
@@ -1326,7 +1326,7 @@ limitations), refer to the section on :ref:`eigen`.
 
 .. seealso::
 
-    The file :file:`example/example-buffers.cpp` contains a complete example
+    The file :file:`tests/test_buffers.cpp` contains a complete example
     that demonstrates using the buffer protocol with pybind11 in more detail.
 
 .. [#f2] http://docs.python.org/3/c-api/buffer.html
@@ -1493,7 +1493,7 @@ simply using ``vectorize``).
 
 .. seealso::
 
-    The file :file:`example/example-numpy-vectorize.cpp` contains a complete
+    The file :file:`tests/test_numpy_vectorize.cpp` contains a complete
     example that demonstrates using :func:`vectorize` in more detail.
 
 Functions taking Python objects as arguments
@@ -1557,9 +1557,9 @@ with other parameters.
 
 .. seealso::
 
-    The file :file:`example/example-python-types.cpp` contains a complete
+    The file :file:`tests/test_python_types.cpp` contains a complete
     example that demonstrates passing native Python types in more detail. The
-    file :file:`example/example-arg-keywords-and-defaults.cpp` discusses usage
+    file :file:`tests/test_kwargs_and_defaults.cpp` discusses usage
     of ``args`` and ``kwargs``.
 
 Default arguments revisited
@@ -1633,7 +1633,7 @@ Such functions can also be created using pybind11:
    /// Binding code
    m.def("generic", &generic);
 
-(See ``example/example-arg-keywords-and-defaults.cpp``). The class ``py::args``
+(See ``tests/test_kwargs_and_defaults.cpp``). The class ``py::args``
 derives from ``py::list`` and ``py::kwargs`` derives from ``py::dict`` Note
 that the ``kwargs`` argument is invalid if no keyword arguments were actually
 provided.  Please refer to the other examples for details on how to iterate
@@ -1783,7 +1783,7 @@ memory corruption and/or segmentation faults.
 
 .. seealso::
 
-    The file :file:`example/example-pickling.cpp` contains a complete example
+    The file :file:`tests/test_pickling.cpp` contains a complete example
     that demonstrates how to pickle and unpickle types using pybind11 in more
     detail.
 
diff --git a/docs/basics.rst b/docs/basics.rst
index 1f40f198d..394c22beb 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -5,7 +5,7 @@ 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.
+included set of test cases.
 
 
 Compiling the test cases
@@ -22,44 +22,42 @@ After installing the prerequisites, run
 
 .. code-block:: bash
 
-   cmake .
-   make -j 4
+   mkdir build
+   cd build
+   cmake ..
+   make pytest -j 4
 
-followed by
-
-.. code-block:: bash
-
-   make test
+The last line will both compile and run the tests.
 
 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:`pybind11.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.
+On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies
+on various C++11 language features that break older versions of Visual Studio.
 
-.. _`CMake GUI`: https://cmake.org/runningcmake
+To compile and run the tests:
+
+.. code-block:: batch
+
+   mkdir build
+   cd build
+   cmake ..
+   cmake --build . --config Release --target pytest
+
+This will create a Visual Studio project, compile and run the target, all from the
+command line.
 
 .. 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.
+    If all tests fail, make sure that the Python binary and the testcases are compiled
+    for the same processor type and bitness (i.e. either **i386** or **x86_64**). You
+    can specify **x86_64** as the target architecture for the generated Visual Studio
+    project using ``cmake -A x64 ..``.
 
 .. 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,
+    the tutorial and look at the test cases in the :file:`tests` directory,
     which exercise all features of pybind11.
 
 Creating bindings for a simple function