IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Closes #671: new autodoc features: :special-members: and :private-members: should respect :undoc-members:. Also :special-members: should not document __doc__.

Browse Source
This commit is contained in:
Georg Brandl 2011-05-15 12:41:45 +02:00
parent 99c505b63f
commit ef674a20a6
1 changed files with 31 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
sphinx/ext/autodoc.py
View File

@ -555,19 +555,6 @@ class Documenter(object):
# if isattr is True, the member is documented as an attribute # if isattr is True, the member is documented as an attribute
isattr = False isattr = False
if want_all and membername.startswith('__') and \
membername.endswith('__') and len(membername) > 4:
# special __methods__
skip = not self.options.special_members
elif want_all and membername.startswith('_'):
# ignore members whose name starts with _ by default
skip = not self.options.private_members
elif (namespace, membername) in attr_docs:
# keep documented attributes
skip = False
isattr = True
else:
# ignore undocumented members if :undoc-members: is not given
doc = self.get_attr(member, '__doc__', None) doc = self.get_attr(member, '__doc__', None)
# if the member __doc__ is the same as self's __doc__, it's just # if the member __doc__ is the same as self's __doc__, it's just
# inherited and therefore not the member's doc # inherited and therefore not the member's doc
@ -576,7 +563,25 @@ class Documenter(object):
cls_doc = self.get_attr(cls, '__doc__', None) cls_doc = self.get_attr(cls, '__doc__', None)
if cls_doc == doc: if cls_doc == doc:
doc = None doc = None
skip = not self.options.undoc_members and not doc has_doc = bool(doc)
keep = False
if want_all and membername.startswith('__') and \
membername.endswith('__') and len(membername) > 4:
# special __methods__
if self.options.special_members and membername != '__doc__':
keep = has_doc or self.options.undoc_members
elif want_all and membername.startswith('_'):
# ignore members whose name starts with _ by default
keep = self.options.private_members and \
(has_doc or self.options.undoc_members)
elif (namespace, membername) in attr_docs:
# keep documented attributes
keep = True
isattr = True
else:
# ignore undocumented members if :undoc-members: is not given
keep = has_doc or self.options.undoc_members
# give the user a chance to decide whether this member # give the user a chance to decide whether this member
# should be skipped # should be skipped
@ -584,12 +589,11 @@ class Documenter(object):
# let extensions preprocess docstrings # let extensions preprocess docstrings
skip_user = self.env.app.emit_firstresult( skip_user = self.env.app.emit_firstresult(
'autodoc-skip-member', self.objtype, membername, member, 'autodoc-skip-member', self.objtype, membername, member,
skip, self.options) not keep, self.options)
if skip_user is not None: if skip_user is not None:
skip = skip_user keep = not skip_user
if skip:
continue
if keep:
ret.append((membername, member, isattr)) ret.append((membername, member, isattr))
return ret return ret
@ -1348,3 +1352,13 @@ def setup(app):
app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-docstring')
app.add_event('autodoc-process-signature') app.add_event('autodoc-process-signature')
app.add_event('autodoc-skip-member') app.add_event('autodoc-skip-member')
class testcls:
"""test doc string"""
def __getattr__(self, x):
return x
def __setattr__(self, x, y):
"""Attr setter."""