Introduce @public marker to explicitly mark members as public

[tmeyier]

Here is an implementation of the @public marker, as proposed in #646.

• members with "@public" in the docstring will be considered public by the default jinja2 template and shown in the generated API documentation - even if the member name starts with _.
• the definition in __doc__ has higher precedence than @public
• the "@public" marker is removed from the docstring in the rendered docs. This is done with a simple replace filter. So the @public marker should be added directly before the closing """ of the docstring to avoid additional whitespace in the rendered docs.

closes #645

[mhils]

This looks great, thank you so much for tackling this! 🍰

[mhils]

I think I don't fully understand why there is a second public method here. What are we verifying with that?

[tmeyier]

I wanted to see if there is any unwanted whitespace after the docstring in the generated html. The second method is there only to see how much spacing between methods you get regularly. For the automated test suite it's probably not really useful.

[mhils]

Also sorry @public for the notifications! ❤️ Looks like you're taking this with a bit of humor, which is great. Thank you for your understanding, I'll try to go with @public going forward! 😅 🍰

[public]

I'm used to it :)

[tmeyier]

The code review functionality in github still is a bit confusing for me. Sorry for the git mess.

[mhils]

No worries at all, we'll squash anyways. Thanks again for contributing this, this is really cool! 😃 🍰