Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

ben-spiller opened this issue Nov 15, 2019 · 5 comments


Copy link

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.


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
Copy link

tk0miya commented Nov 16, 2019

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

@tk0miya tk0miya added this to the 2.4.0 milestone Nov 16, 2019
Copy link

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

Copy link

tk0miya commented Nov 20, 2019

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.

Copy link

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

tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 1, 2020
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 3, 2020
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 3, 2020
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 3, 2020
@tk0miya tk0miya modified the milestones: 2.4.0, 3.0.0 Jan 3, 2020
Copy link

tk0miya commented Jan 3, 2020

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 .


tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 3, 2020
tk0miya added a commit that referenced this issue Jan 11, 2020
Close #6830: autodoc: consider a member private if docstring contains :private:
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 29, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
None yet

No branches or pull requests

2 participants