From a439ccaa0e41899f0f656f798891ea1b3d999951 Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel.jakob@epfl.ch>
Date: Tue, 17 May 2016 10:47:52 +0200
Subject: [PATCH] minor FAQ edits, referenced cppimport project

---
 docs/{cmake.rst => compiling.rst} | 10 +++++++++
 docs/faq.rst                      | 37 ++++++++++++++++---------------
 docs/index.rst                    |  2 +-
 3 files changed, 30 insertions(+), 19 deletions(-)
 rename docs/{cmake.rst => compiling.rst} (94%)

diff --git a/docs/cmake.rst b/docs/compiling.rst
similarity index 94%
rename from docs/cmake.rst
rename to docs/compiling.rst
index d405bc395..5f4d09836 100644
--- a/docs/cmake.rst
+++ b/docs/compiling.rst
@@ -11,6 +11,16 @@ the [pbtest]_ repository.
 
 .. [pbtest] https://github.com/pybind/pbtest
 
+Building with cppimport
+========================
+
+ cppimport is a small Python import hook that determines whether there is a C++
+ source file whose name matches the requested module. If there is, the file is
+ compiled as a Python extension using pybind11 and placed in the same folder as
+ the C++ source file. Python is then able to find the module and load it.
+
+.. [cppimport] https://github.com/tbenthompson/cppimport
+
 .. _cmake:
 
 Building with CMake
diff --git a/docs/faq.rst b/docs/faq.rst
index 4304f06b2..b6c91a8bd 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -24,6 +24,25 @@ The Python interpreter immediately crashes when importing my module
 
 See item 2 of the first answer.
 
+CMake doesn't detect the right Python version, or it finds mismatched interpreter and library versions
+======================================================================================================
+
+The Python detection logic of CMake is flawed and can sometimes fail to find
+the desired Python version, or it chooses mismatched interpreter and library
+versions. A longer discussion is available on the pybind11 issue tracker
+[#f1]_, though this is ultimately not a pybind11 issue.
+
+To force the build system to choose a particular version, delete CMakeCache.txt
+and then invoke CMake as follows:
+
+.. code-block:: bash
+
+    cmake -DPYTHON_EXECUTABLE:FILEPATH=<...> \
+          -DPYTHON_LIBRARY:FILEPATH=<...>  \
+          -DPYTHON_INCLUDE_DIR:PATH=<...> .
+
+.. [#f1] http://github.com/pybind/pybind11/issues/99
+
 Limitations involving reference arguments
 =========================================
 
@@ -72,24 +91,6 @@ and the binding code
 
    m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
 
-CMake doesn't detect the right Python version, or it finds mismatched interpreter and library versions
-======================================================================================================
-
-The Python detection logic of CMake is flawed and can sometimes fail to find
-the desired Python version, or it chooses mismatched interpreter and library
-versions. A longer discussion is available on the pybind11 issue tracker
-[#f1]_, though this is ultimately not a pybind11 issue.
-
-To force the build system to choose a particular version, delete CMakeCache.txt
-and then invoke CMake as follows:
-
-.. code-block:: bash
-
-    cmake -DPYTHON_EXECUTABLE:FILEPATH=<...> \
-          -DPYTHON_LIBRARY:FILEPATH=<...>  \
-          -DPYTHON_INCLUDE_DIR:PATH=<...> .
-
-.. [#f1] http://github.com/pybind/pybind11/issues/99
 
 How can I reduce the build time?
 ================================
diff --git a/docs/index.rst b/docs/index.rst
index 511517102..ab9a1fc82 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,7 +16,7 @@ pybind11 --- Seamless operability between C++11 and Python
    basics
    classes
    advanced
-   cmake
+   compiling
    benchmark
    limitations
    faq