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

attribute documentation now overrides non attribute documentation.

Browse Source 
This makes it possible to document aliased methods and other things::

    def foo(self):
        pass

    #: an alias for foo()
    foo_alias = foo

Also attribute documentation can contain paragraphs now.
This commit is contained in:
Armin Ronacher 2009-02-05 13:28:46 +01:00
parent 4f21cce12e
commit bf943483c0
2 changed files with 25 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
sphinx/ext/autodoc.py
View File

@ -359,7 +359,7 @@ class RstGenerator(object):
return ''
def generate(self, what, name, members, add_content, indent=u'', check_module=False,
no_docstring=False):
no_docstring=False, real_module=None):
"""
Generate reST for the object in self.result.
"""
@ -388,9 +388,17 @@ class RstGenerator(object):
(what, str(fullname), err))
return
# if there is no real-module defined figure out which to use. The real module
# is used in the module analyzer to look up the module where the attribute
# documentation would actually be found in.
# This is used for situations where you have a module that collects the
# functions and classes of internal submodules.
if real_module is None:
real_module = getattr(todoc, '__module__', None) or mod
# try to also get a source code analyzer for attribute docs
try:
analyzer = ModuleAnalyzer.for_module(mod)
analyzer = ModuleAnalyzer.for_module(real_module)
# parse right now, to get PycodeErrors on parsing
analyzer.parse()
except PycodeError, err:
@ -465,14 +473,13 @@ class RstGenerator(object):
sys.getfilesystemencoding(), 'replace')
sourcename = u'%s:docstring of %s' % (srcname, fullname)
attr_docs = analyzer.find_attr_docs()
if what in ('data', 'attribute'):
key = ('.'.join(objpath[:-1]), objpath[-1])
if key in attr_docs:
no_docstring = True
docstrings = [attr_docs[key]]
for i, line in enumerate(self.process_doc(docstrings, what,
fullname, todoc)):
self.result.append(indent + line, sourcename, i)
key = ('.'.join(objpath[:-1]), objpath[-1])
if key in attr_docs:
no_docstring = True
docstrings = [attr_docs[key]]
for i, line in enumerate(self.process_doc(docstrings, what,
fullname, todoc)):
self.result.append(indent + line, sourcename, i)
else:
sourcename = u'docstring of %s' % fullname
attr_docs = {}
@ -605,7 +612,8 @@ class RstGenerator(object):
full_membername = mod + '::' + '.'.join(objpath + [membername])
self.generate(memberwhat, full_membername, ['__all__'],
add_content=content, no_docstring=bool(content),
indent=indent, check_module=members_check_module)
indent=indent, check_module=members_check_module,
real_module=real_module)
self.env.autodoc_current_module = None
self.env.autodoc_current_class = None

8
sphinx/util/docstrings.py
View File

@ -49,8 +49,12 @@ def prepare_commentdoc(s):
result = []
lines = [line.strip() for line in s.expandtabs().splitlines()]
for line in lines:
if line.startswith('#: '):
result.append(line[3:])
if line.startswith('#:'):
line = line[2:]
# the first space after the comment is ignored
if line and line[0] == ' ':
line = line[1:]
result.append(line)
if result and result[-1]:
result.append('')
return result