> I could add an assertion about the last 3 path components of __file__ so that we know when something goes wrong immediately...

that would improve the situation. But what is wrong with

~~~~~
d = __file__
for i in range(10):
    d = os.path.abspath(os.path.join(d, os.path.pardir))
    if os.path.isdir(os.path.join(d, "plugin")) and os.path.isdir(os.path.join(d, "doc")):
         return d
assert 0, "Unable to find the plugin directory."
~~~~~