Thanks for the report.  After reviewing the situation, I think this is actually a code bug rather than a documentation issue; in other words, things should work like the embedding documentation states.

sysconfig has a complicated history; there are currently 6 copies of sysconfig being actively maintained: Lib/sysconfig.py and Lib/distutils/sysconfig.py in each of the default (in progress 3.5), 3.4, and 2.7 branches. 5 of the 6 versions have get_makefile_filename; only the 2.7 Lib/sysconfig.py copy has _get_makefile_filename.  Some of the history details here are probably not entirely accurate but I believe the basic story is as follows.  Historically, there was only a distutils/sysconfig.py and it has had a documented get_makefile_filename() for nearly forever.  Then, during the 2.7 and 3.2 development cycles, a lot of effort went into new features for distutils, including creating Lib/sysconfig.py as a system-wide replacement for the distutils one.  As part of that feature, the get_makefile_filename function was, for some reason, deprecated and renamed to _get_makefile_filename in both the original distutils and the new Lib copies.  Later in the dev cycle, it was decided that it would be better to avoid making major changes to distutils (and the distutils2 project was started and later abandonded); as a result, the changes to distutils itself were reverted (mostly) prior to the 2.7 and 3.2 releases.  But the new Lib/sysconfig version was not modified to conform to the original (and now reverted to) name in the distutils version.  Still later, this discrepancy was noticed and Issue9877 was opened to change the name in Lib/sysconfig.py to get_makefile_file prior to its release in 3.2 but this was after Lib/sysconfig.py had already been released in 2.7 and the history of the otherwise reverted change in 2.7 may have been overlooked.  In any case, we now have this situation where Lib/sysconfig.py in 2.7 doesn't quite match any of the other versions, include its 2.7 Lib/distutils/sysconfig.py twin.

Although Lib/sysconfig.py _get_makefile_filename has never been documented, I think the safest and correct course of action is to change and document the name in 2.7 Lib/sysconfig.py but also continue to provide _get_makefile_filename as an alias.  The attached patch should do that.


https://docs.python.org/2/library/sysconfig.html
https://docs.python.org/3/library/sysconfig.html#sysconfig.get_makefile_filename
https://docs.python.org/2/distutils/apiref.html#distutils.sysconfig.get_makefile_filename
https://docs.python.org/3/distutils/apiref.html#distutils.sysconfig.get_makefile_filename