Docs: move build notes to build section, update w/ #921

Author: aldanor

docs/basics.rst

@@ -120,47 +120,10 @@ generates binding code that exposes the ``add()`` function to Python.
     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, the above example can be compiled using the following command:
-
-.. code-block:: bash
-
-    $ c++ -O3 -Wall -shared -std=c++11 -fPIC -I$PYBIND11_INCLUDE `python3-config --includes` example.cpp -o example`python3-config --extension-suffix`
-
-where ``PYBIND11_INCLUDE`` is the path to the include folder of pybind11.
-If pybind11 installed as a Python package, it can be obtained as follows:
-
-.. code-block:: bash
-
-   $ PYBIND11_INCLUDE=`python -c 'import pybind11; print(pybind11.get_include())'`
-
-Note that for some Python distributions the list of Python's system include
-folders contains the one where pybind11 gets installed, in which case
-passing ``-I$PYBIND11_INCLUDE`` is optional.
-
-On Python 2.7.x: ``python-config`` has to be used instead of ``python3-config``
-in the command above. Besides, ``--extension-suffix`` option may or may not
-be available, depending on the distribution; in the latter case, the module
-extension can be manually set to ``.so``.
-
-On Mac OS: the build command is almost the same but it also requires passing
-the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when
-building the module:
-
-.. code-block:: bash
-
-    $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup -I$PYBIND11_INCLUDE `python3-config --includes` example.cpp -o example`python3-config --extension-suffix`
-
-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 compiled module is located in the current directory, the
-following interactive Python session shows how to load and execute the example.
+Building the above C++ code (refer to :ref:`compiling` for details) will produce
+a binary module file that can be imported to Python. Assuming that the compiled
+module is located in the current directory, the following interactive Python
+session shows how to load and execute the example:
 
 .. code-block:: pycon
 

docs/compiling.rst

@@ -1,6 +1,38 @@
+.. _compiling:
+
 Build systems
 #############
 
+Building manually
+=================
+
+pybind11 is a header-only-library, hence it is not necessary to link against
+any special libraries (other than Python itself).
+
+On Linux, the above example can be compiled using the following command:
+
+.. code-block:: bash
+
+    $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
+
+Note that on Python 2.7.x ``python-config`` has to be used instead of
+``python3-config`` in the command above. Besides, ``--extension-suffix``
+option may or may not be available, depending on the distribution; in the latter
+case, the module extension can be manually set to ``.so``.
+
+On Mac OS: the build command is almost the same but it also requires passing
+the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when
+building the module:
+
+.. code-block:: bash
+
+    $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup `python -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
+
+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 that works on all platforms including Windows.
+
 Building with setuptools
 ========================