Add :showdoc: directive (RFC #11)

[nobodywasishere]

Implements RFC#0011.

Starting as a draft for now to get feedback.

[nobodywasishere]

(apologies for force push, force of habit)

[ysbaddaden]

That looks pretty good and seems to do the job well 👍

[Blacksmoke16]

Given this PR is implementing an RFC for :showdoc: should we save the extra stuff for future PRs? There seems to be more going on than just supporting this new directive.

[nobodywasishere]

There seems to be more going on than just supporting this new directive.

What stuff are you referring to?

[Blacksmoke16]

From what I can tell this is also enabling doc support on lib related types yea?

[nobodywasishere]

Yes that's true. I'm fine splitting it into two PRs, but enabling documentation support for lib types was the original purpose for the :showdoc: directive. The RFC encapsulates both the documentation of lib types, and the directive for enabling the documentation of those types (alongside private/protected ones).

[straight-shoota]

I think splitting this into separate PRs is a good idea. The changes are all working towards the goal to support API docs for lib bindings. But they're not directly related. The doc generator changes and the parser changes for example do not strictly depend on each other. We can merge either one individually and have a subset of features available.
Splitting makes the changes smaller, easier to review, and easier to reason about in the future when someone is wondering what's been happening here.

[nobodywasishere]

Sounds good. How should I go about splitting this PR? As we discourage force-pushing, my thought is closing this PR and opening two others (one for lib docs, another for showdoc directive)