docs: add a note about compiling the example (#2737)

* docs: mention PYTHONPATH in installing.rst

When pybind11 is included as a submodule, the user needs to update their
Python module search path.  Otherwise, the first c++ compilation command
in docs/basics.rst will fail.

* docs: add a note about compiling the example

This note shows how to modify the compilation command for the example
when the pybind11 source has been included as a Git submodule.

* docs: add a note about compiling the example

Added an internal link to the docs

* docs: updated a note about compiling the example

Also updated the command substitution syntax for consistency

docs/basics.rst

@@ -136,7 +136,14 @@ On Linux, the above example can be compiled using the following command:
 
 
 .. code-block:: bash
 .. code-block:: bash
 
 
-    $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
+    $ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
+
+.. note::
+
+    If you used :ref:`include_as_a_submodule` to get the pybind11 source, then
+    use ``$(python3-config --includes) -Iextern/pybind11/include`` instead of
+    ``$(python3 -m pybind11 --includes)`` in the above compilation, as
+    explained in :ref:`building_manually`.
 
 
 For more details on the required compiler flags on Linux and macOS, see
 For more details on the required compiler flags on Linux and macOS, see
 :ref:`building_manually`. For complete cross-platform compilation instructions,
 :ref:`building_manually`. For complete cross-platform compilation instructions,

docs/compiling.rst

@@ -565,7 +565,7 @@ On Linux, you can compile an example such as the one given in
 
 
 .. code-block:: bash
 .. code-block:: bash
 
 
-    $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
+    $ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
 
 
 The flags given here assume that you're using Python 3. For Python 2, just
 The flags given here assume that you're using Python 3. For Python 2, just
 change the executable appropriately (to ``python`` or ``python2``).
 change the executable appropriately (to ``python`` or ``python2``).
@@ -577,7 +577,7 @@ using ``pip`` or ``conda``. If it hasn't, you can also manually specify
 ``python3-config --includes``.
 ``python3-config --includes``.
 
 
 Note that Python 2.7 modules don't use a special suffix, so you should simply
 Note that Python 2.7 modules don't use a special suffix, so you should simply
-use ``example.so`` instead of ``example`python3-config --extension-suffix```.
+use ``example.so`` instead of ``example$(python3-config --extension-suffix)``.
 Besides, the ``--extension-suffix`` option may or may not be available, depending
 Besides, the ``--extension-suffix`` option may or may not be available, depending
 on the distribution; in the latter case, the module extension can be manually
 on the distribution; in the latter case, the module extension can be manually
 set to ``.so``.
 set to ``.so``.
@@ -588,7 +588,7 @@ building the module:
 
 
 .. code-block:: bash
 .. code-block:: bash
 
 
-    $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
+    $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
 
 
 In general, it is advisable to include several additional build parameters
 In general, it is advisable to include several additional build parameters
 that can considerably reduce the size of the created binary. Refer to section
 that can considerably reduce the size of the created binary. Refer to section

docs/installing.rst

@@ -8,6 +8,8 @@ There are several ways to get the pybind11 source, which lives at
 developers recommend one of the first three ways listed here, submodule, PyPI,
 developers recommend one of the first three ways listed here, submodule, PyPI,
 or conda-forge, for obtaining pybind11.
 or conda-forge, for obtaining pybind11.
 
 
+.. _include_as_a_submodule:
+
 Include as a submodule
 Include as a submodule
 ======================
 ======================