[Python-checkins] r64483 - in doctools/trunk: CHANGES doc/markup/desc.rst sphinx/addnodes.py sphinx/directives/desc.py sphinx/ext/autodoc.py sphinx/htmlwriter.py sphinx/latexwriter.py sphinx/texinputs/sphinx.sty

Mon Jun 23 14:04:57 CEST 2008

Author: georg.brandl
Date: Mon Jun 23 14:04:56 2008
New Revision: 64483
Log:
Add static method support.
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/doc/markup/desc.rst
 doctools/trunk/sphinx/addnodes.py
 doctools/trunk/sphinx/directives/desc.py
 doctools/trunk/sphinx/ext/autodoc.py
 doctools/trunk/sphinx/htmlwriter.py
 doctools/trunk/sphinx/latexwriter.py
 doctools/trunk/sphinx/texinputs/sphinx.sty
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Mon Jun 23 14:04:56 2008
@@ -13,6 +13,9 @@
 * Sphinx now interprets field lists with fields like ``:param foo:``
 in description units.
 
+* The new `staticmethod` directive can be used to mark methods as
+ static methods.
+ 
 * HTML output:
 
 - The "previous" and "next" links have a more logical structure, so
Modified: doctools/trunk/doc/markup/desc.rst
==============================================================================
--- doctools/trunk/doc/markup/desc.rst	(original)
+++ doctools/trunk/doc/markup/desc.rst	Mon Jun 23 14:04:56 2008
@@ -199,6 +199,12 @@
 parameter. The description should include similar information to that
 described for ``function``. See also :ref:`signatures`.
 
+.. directive:: .. staticmethod:: name(signature)
+
+ Like :dir:`method`, but indicates that the method is a static method.
+
+ .. versionadded:: 0.4
+ 
 .. directive:: .. opcode:: name
 
 Describes a Python bytecode instruction (this is not very useful for projects
Modified: doctools/trunk/sphinx/addnodes.py
==============================================================================
--- doctools/trunk/sphinx/addnodes.py	(original)
+++ doctools/trunk/sphinx/addnodes.py	Mon Jun 23 14:04:56 2008
@@ -23,7 +23,7 @@
 class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement): pass
 # compatibility alias
 desc_classname = desc_addname
-# return type (C), object type (Python)
+# return type (C); object type, e.g. -> annotation (Python)
 class desc_type(nodes.Part, nodes.Inline, nodes.TextElement): pass
 # main name of object
 class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass
@@ -36,6 +36,8 @@
 child_text_separator = ', '
 def astext(self):
 return '[' + nodes.TextElement.astext(self) + ']'
+# annotation (not Python 3-style annotations)
+class desc_annotation(nodes.Part, nodes.Inline, nodes.TextElement): pass
 
 # node for content
 class desc_content(nodes.General, nodes.Element): pass
Modified: doctools/trunk/sphinx/directives/desc.py
==============================================================================
--- doctools/trunk/sphinx/directives/desc.py	(original)
+++ doctools/trunk/sphinx/directives/desc.py	Mon Jun 23 14:04:56 2008
@@ -45,6 +45,18 @@
 return '%s() (%s.%s method)' % (methname, module, clsname)
 else:
 return '%s() (%s method)' % (methname, clsname)
+ elif desctype == 'staticmethod':
+ try:
+ clsname, methname = name.rsplit('.', 1)
+ except ValueError:
+ if module:
+ return '%s() (in module %s)' % (name, module)
+ else:
+ return '%s()' % name
+ if module:
+ return '%s() (%s.%s static method)' % (methname, module, clsname)
+ else:
+ return '%s() (%s static method)' % (methname, clsname)
 elif desctype == 'attribute':
 try:
 clsname, attrname = name.rsplit('.', 1)
@@ -91,6 +103,8 @@
 'var': 'Variable',
 'ivar': 'Variable',
 'cvar': 'Variable',
+ 'returns': 'Returns',
+ 'return': 'Returns',
 }
 
 doc_fields_without_arg = {
@@ -140,7 +154,7 @@
 nfield = nodes.field()
 nfield += nodes.field_name(typ, typ)
 nfield += nodes.field_body()
- nfield[1] += children
+ nfield[1] += fbody.children
 new_list += nfield
 except (KeyError, ValueError):
 fnametext = fname.astext()
@@ -199,6 +213,9 @@
 add_module = True
 fullname = classname and classname + name or name
 
+ if desctype == 'staticmethod':
+ signode += addnodes.desc_annotation('static ', 'static ')
+
 if classname:
 signode += addnodes.desc_addname(classname, classname)
 # exceptions are a special case, since they are documented in the
@@ -210,7 +227,7 @@
 
 signode += addnodes.desc_name(name, name)
 if not arglist:
- if desctype in ('function', 'method'):
+ if desctype in ('function', 'method', 'staticmethod'):
 # for callables, add an empty parameter list
 signode += addnodes.desc_parameterlist()
 return fullname, classname
@@ -383,7 +400,7 @@
 node.append(signode)
 try:
 if desctype in ('function', 'data', 'class', 'exception',
- 'method', 'attribute'):
+ 'method', 'staticmethod', 'attribute'):
 name, clsname = parse_py_signature(signode, sig, desctype, module, env)
 elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'):
 name = parse_c_signature(signode, sig, desctype)
@@ -457,7 +474,8 @@
 if desctype in ('class', 'exception') and names:
 env.currclass = names[0]
 clsname_set = True
- elif desctype in ('method', 'attribute') and clsname and not env.currclass:
+ elif desctype in ('method', 'staticmethod', 'attribute') and \
+ clsname and not env.currclass:
 env.currclass = clsname.strip('.')
 clsname_set = True
 # needed for association of version{added,changed} directives
@@ -482,6 +500,7 @@
 'data',
 'class',
 'method',
+ 'staticmethod',
 'attribute',
 'exception',
 # the C ones
Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Mon Jun 23 14:04:56 2008
@@ -254,7 +254,6 @@
 def generate_rst(what, name, members, options, add_content, document, lineno,
 indent=u'', filename_set=None, check_module=False):
 env = document.settings.env
- is_static = False
 
 result = None
 
Modified: doctools/trunk/sphinx/htmlwriter.py
==============================================================================
--- doctools/trunk/sphinx/htmlwriter.py	(original)
+++ doctools/trunk/sphinx/htmlwriter.py	Mon Jun 23 14:04:56 2008
@@ -113,6 +113,11 @@
 def depart_desc_optional(self, node):
 self.body.append('<span class="optional">]</span>')
 
+ def visit_desc_annotation(self, node):
+ self.body.append(self.starttag(node, 'em', CLASS='property'))
+ def depart_desc_annotation(self, node):
+ self.body.append('</em>')
+
 def visit_desc_content(self, node):
 self.body.append(self.starttag(node, 'dd', ''))
 def depart_desc_content(self, node):
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Mon Jun 23 14:04:56 2008
@@ -86,7 +86,7 @@
 def __init__(self, node):
 self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe')
 self.ni = node['noindex']
- self.type = self.cls = self.name = self.params = ''
+ self.type = self.cls = self.name = self.params = self.annotation = ''
 self.count = 0
 
 
@@ -284,6 +284,7 @@
 'function' : 'funcdesc',
 'class': 'classdesc',
 'method': 'methoddesc',
+ 'staticmethod': 'staticmethoddesc',
 'exception': 'excdesc',
 'data': 'datadesc',
 'attribute': 'memberdesc',
@@ -325,7 +326,7 @@
 t2 = "{%s}{%s}" % (d.name, d.params)
 elif d.env in ('datadesc', 'classdesc*', 'excdesc', 'csimplemacrodesc'):
 t2 = "{%s}" % (d.name)
- elif d.env == 'methoddesc':
+ elif d.env in ('methoddesc', 'staticmethoddesc'):
 if d.cls:
 t2 = "[%s]{%s}{%s}" % (d.cls, d.name, d.params)
 else:
@@ -390,6 +391,14 @@
 self.descstack[-1].params = self.encode(node.astext().strip())
 raise nodes.SkipNode
 
+ def visit_desc_annotation(self, node):
+ d = self.descstack[-1]
+ if d.env == 'describe':
+ d.name += self.encode(node.astext())
+ else:
+ self.descstack[-1].annotation = self.encode(node.astext().strip())
+ raise nodes.SkipNode
+
 def visit_refcount(self, node):
 self.body.append("\\emph{")
 def depart_refcount(self, node):
Modified: doctools/trunk/sphinx/texinputs/sphinx.sty
==============================================================================
--- doctools/trunk/sphinx/texinputs/sphinx.sty	(original)
+++ doctools/trunk/sphinx/texinputs/sphinx.sty	Mon Jun 23 14:04:56 2008
@@ -572,6 +572,35 @@
 \methodlineni{#2}{#3}
 }{\end{fulllineitems}}
 
+% static method ----------------------------------------------------------
+% \begin{staticmethoddesc}[classname]{methodname}{args}
+\newcommand{\staticmethodline}[3][\@undefined]{
+ \staticmethodlineni{#2}{#3}
+ \ifx\@undefined#1\relax
+ \index{#2@{\py at idxcode{#2()}} (\py at thisclass\ static method)}
+ \else
+ \index{#2@{\py at idxcode{#2()}} (#1 static method)}
+ \fi
+}
+\newenvironment{staticmethoddesc}[3][\@undefined]{
+ \begin{fulllineitems}
+ \ifx\@undefined#1\relax
+ \staticmethodline{#2}{#3}
+ \else
+ \def\py at thisclass{#1}
+ \staticmethodline{#2}{#3}
+ \fi
+}{\end{fulllineitems}}
+
+% similar to {staticmethoddesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\staticmethodlineni}[3][\py at classbadkey]{%
+ \py at sigline{static \bfcode{#2}}{#3}}
+\newenvironment{staticmethoddescni}[3][\py at classbadkey]{
+ \begin{fulllineitems}
+ \staticmethodlineni{#2}{#3}
+}{\end{fulllineitems}}
+
 % object data attribute --------------------------------------------------
 % \begin{memberdesc}[classname]{membername}
 \newcommand{\memberline}[2][\py at classbadkey]{%
