Aye, it's definitely a tricky problem. While I didn't take them into account in my review, I now realise those issues also impacted the attempted workaround - I'd be surprised if it worked as intended in those other contexts (even the "pydoc -b" rendered HTML view).

As far as how to deal with the rendering complexity in a protocol, one possible way to go would be to say that rather than returning a fully rendered string, __help__() methods should return either a Python function object or a type() instance (that doesn't define __help__()), and then pydoc would render the help based on that.

Regardless of the exact approach, it would be a task requiring a PEP to resolve, since rendered documentation appears in so many different contexts.