[Python-checkins] r62776 - in doctools/trunk: CHANGES doc/ext/autodoc.rst sphinx/ext/autodoc.py
armin.ronacher
python-checkins at python.org
Tue May 6 20:07:18 CEST 2008
Author: armin.ronacher
Date: Tue May 6 20:07:17 2008
New Revision: 62776
Log:
added support for explicit signatures in callables
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/ext/autodoc.rst
doctools/trunk/sphinx/ext/autodoc.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Tue May 6 20:07:17 2008
@@ -7,6 +7,9 @@
* A new config value, `html_file_suffix`, can be used to set the HTML file
suffix to e.g. ``.xhtml``.
+* the `autodoc` extension accepts signatures for functions, methods and
+ classes now that override the signature from the python code.
+
Release 0.3 (May 6, 2008)
=========================
Modified: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- doctools/trunk/doc/ext/autodoc.rst (original)
+++ doctools/trunk/doc/ext/autodoc.rst Tue May 6 20:07:17 2008
@@ -67,6 +67,17 @@
For classes and exceptions, members inherited from base classes will be
left out, unless you give the ``inherited-members`` flag option.
+ .. versionadded:: 0.4
+ It's possible to override the signature for callable members (functions,
+ methods, classes) with the regular syntax that will override the signature
+ gained from instropection::
+
+ .. autoclass:: Noodle(type)
+
+ .. automethod:: eat(persona)
+
+ This is useful if the signature from the method is hidden by a decorator.
+
The "auto" directives can also contain content of their own, it will be
inserted into the resulting non-auto directive source after the docstring
(but before any automatic member documentation).
Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py (original)
+++ doctools/trunk/sphinx/ext/autodoc.py Tue May 6 20:07:17 2008
@@ -22,6 +22,7 @@
from docutils.statemachine import ViewList
from sphinx.util import rpartition
+from sphinx.directives.desc import py_sig_re
try:
base_exception = BaseException
@@ -82,19 +83,29 @@
lineno, indent='', filename_set=None, check_module=False):
env = document.settings.env
+ # parse the definition
+ try:
+ mod, obj, signature = py_sig_re.match(name).groups()
+ except:
+ warning = document.reporter.warning(
+ 'invalid definition for %r (%s)' % (what, name), line=lineno)
+ return [warning], ViewList()
+ basename = (mod or '') + obj
+ if mod:
+ mod = mod.rstrip('.')
+
# find out what to import
if what == 'module':
- mod = obj = name
+ mod = basename
objpath = []
elif what in ('class', 'exception', 'function'):
- mod, obj = rpartition(name, '.')
if not mod and hasattr(env, 'autodoc_current_module'):
mod = env.autodoc_current_module
if not mod:
mod = env.currmodule
objpath = [obj]
else:
- mod_cls, obj = rpartition(name, '.')
+ mod_cls = mod
if not mod_cls and hasattr(env, 'autodoc_current_class'):
mod_cls = env.autodoc_current_class
if not mod_cls:
@@ -106,8 +117,10 @@
mod = env.currmodule
objpath = [cls, obj]
+ qualname = '.'.join(objpath) or mod
result = ViewList()
docstrings = []
+ warnings = []
if mod is None:
warning = document.reporter.warning(
@@ -139,28 +152,27 @@
return [warning], result
# add directive header
- try:
- if what == 'class':
- args = inspect.formatargspec(*inspect.getargspec(todoc.__init__))
- if args[1:7] == 'self, ':
- args = '(' + args[7:]
- elif args == '(self)':
- args = '()'
- elif what in ('function', 'method'):
- args = inspect.formatargspec(*inspect.getargspec(todoc))
- if what == 'method':
+ if signature is not None:
+ args = '(%s)' % signature
+ else:
+ try:
+ if what == 'class':
+ args = inspect.formatargspec(*inspect.getargspec(todoc.__init__))
if args[1:7] == 'self, ':
args = '(' + args[7:]
elif args == '(self)':
args = '()'
- else:
+ elif what in ('function', 'method'):
+ args = inspect.formatargspec(*inspect.getargspec(todoc))
+ if what == 'method':
+ if args[1:7] == 'self, ':
+ args = '(' + args[7:]
+ elif args == '(self)':
+ args = '()'
+ else:
+ args = ''
+ except Exception:
args = ''
- except Exception:
- args = ''
- if len(objpath) == 2:
- qualname = '%s.%s' % (cls, obj)
- else:
- qualname = obj
result.append(indent + '.. %s:: %s%s' % (what, qualname, args), '<autodoc>')
result.append('', '<autodoc>')
@@ -211,7 +223,6 @@
if objpath:
env.autodoc_current_class = objpath[0]
- warnings = []
# add members, if possible
_all = members == ['__all__']
members_check_module = False
@@ -256,7 +267,7 @@
else:
# XXX: todo -- attribute docs
continue
- full_membername = name + '.' + membername
+ full_membername = basename + '.' + membername
subwarn, subres = generate_rst(memberwhat, full_membername, ['__all__'],
inherited, undoc, None, document, lineno,
indent, check_module=members_check_module)
More information about the Python-checkins
mailing list