Ensure python header version matches lib version.

There was an error in the foreach() loop over _Python_VERSIONS.
Even if the python library for a specific version was not found,
it would try to find the include file for that python version.
As a result, it could very easily find the include file for one
version of python, and the library for another version.  This has
been seen to happen on OS X, but could happen on any OS.

Change-Id: I90157ba517dadd7d1ba0ce1f5dba523246064581
Remove the deprecated PYTHON_INCLUDE_PATH variable.

This variable has been deprecated for years and its presence can
lead to extreme frustration.  If it is set in the cache, then it
is used as the PYTHON_INCLUDE_DIR.  That means that if someone
removes PYTHON_INCLUDE_DIR from their cache (e.g. while trying to
debug their build), then cmake will set PYTHON_INCLUDE_DIR from
the internally cached PYTHON_INCLUDE_PATH instead of searching the
system for Python.h like it should.

Also fix the variable names in the documentation for this macro,
which were different from the names of the variables that were actually
used.

Change-Id: I55d54b9d05085118c97a2e1d417e8e6b31289f8a
Merge topic 'python-version-match' into master

698f17d6 Remove the deprecated PYTHON_INCLUDE_PATH variable.
8d2ae20d Ensure python header version matches lib version.