A ".. private:: True/False" directive to override whether autodoc/autosummary treat a member as private (regardless of underscores)

[ben-spiller]

Is your feature request related to a problem? Please describe.
Two problems:

• some of the items I'm documenting have internal/private APIs that unfortunately do not start with an underscore (but can't be easily renamed). With sphinx autodoc/autosummary configued to skip private members, I want to indicate that those should be to be skipped as well, but since they have docstrings that are useful for internal purposes I don't want to actually delete the docstring.
• although I mostly want to skip items starting with _ or __ occasionally I have APIs that are effectively public but do start with underscores (e.g. sometimes a single underscore is used in Python to indicate a "protected" API for use by subclasses). I'd like to be able to selectively enable documentation of these methods on a case-by-case basis from my docstrings.

Describe the solution you'd like
A directive a bit like "deprecated" that can be used in a docstring to override whether that member is considered private or not, by autodoc and autosummary.

e.g.

def _protectedMethod(self):
   """ .. private:: False

   This is a great method which is in my public API. 
   """

def semanticallyPrivateMethod(self):
   """ .. private:: True

   This is a great internal method, but shouldn't show up in API docs. 
   """

Important detail: needs to work with data/attribute docstrings (i.e. implementation shouldn't rely on doc).

Describe alternatives you've considered

• Could be done via setting undoc-members on parent class/module, but that's really combersome since no locality-of-reference, plus I might want to do a separate sphinx run with private members visible for internal purposes.

• As a workaround I've been able to mostly get it working for autodoc using autodoc-skip-member (though that doesn't work for autosummary, yet) like this; but it'd be better as a core capability, especially as I have no way to get the docstring Sphinx has extracted for any data/attributes.

def autodoc_skip_member(app, what, name, obj, skip, options):
	if obj.__doc__ and '.. private:: True' in obj.__doc__: return True

[tk0miya]

+0: Good idea. But we need to find more appropriate marker for this usage. I feel .. private is not good.

[ben-spiller]

Is it the word "private" you're not keen on, or the use of ".. XXX"?

I could try to come up with some more suggestions, but helpful to know what it is about ".. private::" that you're not keen on

[tk0miya]

Sorry for less words. I thought about this in this a few days. And I got an answer why I felt not good.

1. Using a directive is not appropriate to describe metadata (marker) to me. It is mainly used to build a block level elements.
2. If we use a "private" directive, how does it behave in outside docstrings (ex. index.rst)?
3. Is ".. private::" comfortable for python developers? IMO, it is a bit bother to read a docstring in code.

Just an idea, I feel a little better to use info-field-list like :orphan: instead. It looks like a tag to me.

[ben-spiller]

OK fine.. I was also wondering about which way to jump on that question, so I'd be very happy with :private:

[tk0miya]

In discussion at #6979, we're determined to use :meta private: to represent a private python object. And the feature will be released as 3.0 because it brings breaking change.
In detail, please see #6979 .

Thanks,