The function documenter now add parameters and return value samples

doc/document.rst

@@ -151,7 +151,7 @@ Python source
 ~~~~~~~~~~~~~
 
 .. literalinclude:: ../wsme/sphinxext.py
-    :lines: 23-49
+    :lines: 35-60
     :language: python
 
 Documentation source

wsme/protocols/__init__.py

@@ -50,6 +50,12 @@ class Protocol(object):
     def encode_sample_value(self, datatype, value, format=False):
         return ('none', 'N/A')
 
+    def encode_sample_params(self, params, format=False):
+        return ('none', 'N/A')
+
+    def encode_sample_result(self, datatype, value, format=False):
+        return ('none', 'N/A')
+
 
 def register_protocol(protocol):
     registered_protocols[protocol.name] = protocol

wsme/protocols/restjson.py

@@ -223,3 +223,21 @@ class RestJsonProtocol(RestProtocol):
             indent=4 if format else 0,
             sort_keys=format)
         return ('javascript', content)
+
+    def encode_sample_params(self, params, format=False):
+        kw = {}
+        for name, datatype, value in params:
+            kw[name] = tojson(datatype, value)
+        content = json.dumps(kw, ensure_ascii=False,
+            indent=4 if format else 0,
+            sort_keys=format)
+        return ('javascript', content)
+
+    def encode_sample_result(self, datatype, value, format=False):
+        r = tojson(datatype, value)
+        if self.nest_result:
+            r = {'result': r}
+        content = json.dumps(r, ensure_ascii=False,
+            indent=4 if format else 0,
+            sort_keys=format)
+        return ('javascript', content)

wsme/protocols/restxml.py

@@ -28,7 +28,6 @@ def xml_indent(elem, level=0):
         elem.tail = i
 
 
-
 @generic
 def toxml(datatype, key, value):
     """
@@ -243,6 +242,20 @@ class RestXmlProtocol(RestProtocol):
         if format:
             xml_indent(r)
         content = et.tostring(r)
-            #indent=4 if format else 0,
-            #sort_keys=format)
+        return ('xml', content)
+
+    def encode_sample_params(self, params, format=False):
+        node = et.Element('parameters')
+        for name, datatype, value in params:
+            node.append(toxml(datatype, name, value))
+        if format:
+            xml_indent(node)
+        content = et.tostring(node)
+        return ('xml', content)
+
+    def encode_sample_result(self, datatype, value, format=False):
+        r = toxml(datatype, 'result', value)
+        if format:
+            xml_indent(r)
+        content = et.tostring(r)
         return ('xml', content)

wsme/sphinxext.py

@@ -7,7 +7,7 @@ from sphinx.ext import autodoc
 from sphinx.domains.python import PyClasslike, PyClassmember
 from sphinx.domains import Domain, ObjType
 from sphinx.directives import ObjectDescription
-from sphinx.util.docfields import Field, GroupedField, TypedField
+from sphinx.util.docfields import Field
 from sphinx.util.nodes import make_refnode
 
 from sphinx.roles import XRefRole
@@ -21,6 +21,17 @@ import wsme
 field_re = re.compile(r':(?P<field>\w+)(\s+(?P<name>\w+))?:')
 
 
+def make_sample_object(datatype):
+    if datatype is str:
+        return 'samplestring'
+    if datatype is unicode:
+        return u'sample unicode'
+    if datatype is int:
+        return 5
+    sample_obj = getattr(datatype, 'sample', datatype)()
+    return sample_obj
+
+
 class SampleType(object):
     """A Sample Type"""
 
@@ -158,7 +169,7 @@ class TypeDocumenter(autodoc.ClassDocumenter):
         protocols = [wsme.protocols.getprotocol(p) for p in protocols]
         content = []
         if protocols:
-            sample_obj = getattr(self.object, 'sample', self.object)()
+            sample_obj = make_sample_object(self.object)
             content.extend([
                 l_(u'Data samples:'),
                 u'',
@@ -315,6 +326,9 @@ class FunctionDocumenter(autodoc.MethodDocumenter):
         docstrings = super(FunctionDocumenter, self).get_doc(encoding)
         found_params = set()
 
+        protocols = self.options.protocols or self.env.app.config.wsme_protocols
+        protocols = [wsme.protocols.getprotocol(p) for p in protocols]
+
         for si, docstring in enumerate(docstrings):
             for i, line in enumerate(docstring):
                 m = field_re.match(line)
@@ -360,6 +374,49 @@ class FunctionDocumenter(autodoc.MethodDocumenter):
                 pos = next_param_pos
             docstring = docstrings[pos[0]]
             docstring[pos[1]:pos[1]] = content
+
+        codesamples = []
+
+        if protocols:
+            params = []
+            for arg in self.wsme_fd.arguments:
+                params.append((arg.name, arg.datatype,
+                    make_sample_object(arg.datatype)))
+            codesamples.extend([
+                u':%s:' % l_(u'Parameters samples'),
+                u'    .. cssclass:: toggle',
+                u''
+            ])
+            for protocol in protocols:
+                language, sample = protocol.encode_sample_params(
+                    params, format=True)
+                codesamples.extend([
+                    u' ' * 4 + (protocol.displayname or protocol.name),
+                    u'        .. code-block:: ' + language,
+                    u'',
+                ])
+                codesamples.extend((
+                    u' ' * 12 + line for line in sample.split('\n')))
+
+            if self.wsme_fd.return_type:
+                codesamples.extend([
+                    u':%s:' % l_(u'Return samples'),
+                    u'    .. cssclass:: toggle',
+                    u''
+                ])
+                sample_obj = make_sample_object(self.wsme_fd.return_type)
+                for protocol in protocols:
+                    language, sample = protocol.encode_sample_result(
+                        self.wsme_fd.return_type, sample_obj, format=True)
+                    codesamples.extend([
+                        u' ' * 4 + protocol.displayname or protocol.name,
+                        u'        .. code-block:: ' + language,
+                        u'',
+                    ])
+                    codesamples.extend((
+                        u' ' * 12 + line for line in sample.split('\n')))
+
+        docstrings[0:0] = [codesamples]
         return docstrings
 
     def add_content(self, more_content, no_docstring=False):