This is a good direction - we need to fix the verbiage - One suggestion -

In some situations we are unable to a dynamic library libpythonx.y.so or
libpythonx.z.dylib. if python is statically linked it may not be present at all.
This is OS / installation dependent and cannot be reliably detected in all cases.
In such situation we fail with error: Failed to find a valid python library!.
You may then be required to install additional OS level packages and / or set the precise library location manually during py/initialize!.

Honestly for quite a few of our users a document describing what a shared library is, how we attempt to detect the location of the python shared library, and the above quote would probably also be a good idea but this PR certainly makes things a bit better than they were before.

@cnuernber
I till think the small clarification is better then no detail.

Agreed - the clarification is important and useful.