minor FAQ edits, referenced cppimport project

docs/cmake.rst → 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

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?
 ================================

docs/index.rst

@@ -16,7 +16,7 @@ pybind11 --- Seamless operability between C++11 and Python
    basics
    classes
    advanced
-   cmake
+   compiling
    benchmark
    limitations
    faq