[Python-checkins] r64699 - in doctools/trunk: doc/ext/autodoc.rst sphinx/directives/other.py sphinx/roles.py

[georg.brandl]

Author: georg.brandl
Date: Fri Jul  4 16:27:25 2008
New Revision: 64699

Log:
Merged revisions 64642-64643,64698 via svnmerge from 
svn+ssh://pythondev@svn.python.org/doctools/branches/0.4.x

........
  r64642 | georg.brandl | 2008-07-01 23:02:35 +0200 (Tue, 01 Jul 2008) | 2 lines
  
  #3251: label names are case insensitive.
........
  r64643 | georg.brandl | 2008-07-01 23:24:55 +0200 (Tue, 01 Jul 2008) | 2 lines
  
  Add a note about decorated functions.
........
  r64698 | georg.brandl | 2008-07-04 12:21:09 +0200 (Fri, 04 Jul 2008) | 2 lines
  
  Allow setting current module to None.
........


Modified:
   doctools/trunk/   (props changed)
   doctools/trunk/doc/ext/autodoc.rst
   doctools/trunk/sphinx/directives/other.py
   doctools/trunk/sphinx/roles.py

Modified: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- doctools/trunk/doc/ext/autodoc.rst	(original)
+++ doctools/trunk/doc/ext/autodoc.rst	Fri Jul  4 16:27:25 2008
@@ -136,6 +136,17 @@
    These work exactly like :dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
+   .. note::
+
+      If you document decorated functions or methods, keep in mind that autodoc
+      retrieves its docstrings by importing the module and inspecting the
+      ``__doc__`` attribute of the given function or method.  That means that if
+      a decorator replaces the decorated function with another, it must copy the
+      original ``__doc__`` to the new function.
+
+      From Python 2.5, :func:`functools.wraps` can be used to create
+      well-behaved decorating functions.
+
 
 There are also new config values that you can set:
 

Modified: doctools/trunk/sphinx/directives/other.py
==============================================================================
--- doctools/trunk/sphinx/directives/other.py	(original)
+++ doctools/trunk/sphinx/directives/other.py	Fri Jul  4 16:27:25 2008
@@ -117,7 +117,10 @@
     # stuff in module foo, but links to module foo won't lead here.
     env = state.document.settings.env
     modname = arguments[0].strip()
-    env.currmodule = modname
+    if modname == 'None':
+        env.currmodule = None
+    else:
+        env.currmodule = modname
     return []
 
 currentmodule_directive.arguments = (1, 0, 0)

Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py	(original)
+++ doctools/trunk/sphinx/roles.py	Fri Jul  4 16:27:25 2008
@@ -175,6 +175,9 @@
         # normalize whitespace in definition terms (if the term reference is
         # broken over a line, a newline will be in target)
         target = ws_re.sub(' ', target).lower()
+    elif typ == 'ref':
+        # reST label names are always lowercased
+        target = ws_re.sub('', target).lower()
     else:
         # remove all whitespace to avoid referencing problems
         target = ws_re.sub('', target)