Doc: how to handle "private" objects in docstrings and news fragments #1711

@niccokunzmann https://icalendar.readthedocs.io/en/stable/contribute/development.html#internal-use-only sort of covers it, but I don't think everyone reads it.

In addition, "internal use only" objects are not displayed in the documentation. Their docstrings, of course, remain in the Python source code.

A refactor is development, so ̄\_(ツ)_/ ̄.

There is no truly private object in Python. We chose not to display them in the documentation by not specifying a value for private-members in autodoc_default_options in docs/conf.py.

Sphinx won't warn on such things. It warns when it can't find the object.

I think, however, it's time to start using guidance from Sphinx.

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#marking-objects-as-public-or-private

def my_function(my_arg, my_other_arg):
 """blah blah blah

 :meta private:
 """

I also think that the _ convention to designate privacy is still good.

To summarize, I think I need to write this up for the Contributing docs under Docstring structure and add a mention in Write a good change log entry. I'll create a separate issue from this comment for that.

Originally posted by @stevepiercy in #1702 (comment)