Improve documentation on types

doc/conf.py

@@ -25,7 +25,8 @@ sys.path.insert(0, os.path.abspath('..'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'wsme.sphinxext']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'wsme.sphinxext',
+    'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -229,6 +230,8 @@ wsme_protocols = [
     'restjson', 'restxml', 'soap', 'extdirect'
 ]
 
+intersphinx_mapping = {'python': ('http://docs.python.org/', None)}
+
 
 def setup(app):
     # confval directive taken from the sphinx doc

doc/document.rst

@@ -172,6 +172,10 @@ Result
 
 .. default-domain:: wsme
 
+.. type:: int
+
+    An integer
+
 .. autotype:: wsme.sphinxext.SampleType
     :members:
 

doc/types.rst

@@ -11,15 +11,41 @@ the different protocols will map to theirs own basic types.
 
 The native types are :
 
-    -   :class:`str`
+    -   .. wsme:type:: str
-    -   :class:`unicode`
+    
-    -   :class:`int`
+            A non unicode string (:py:class:`str`)
-    -   :class:`float`
+
-    -   :class:`bool`
+    -   .. wsme:type:: unicode
-    -   :class:`decimal.Decimal`
+
-    -   :class:`datetime.date`
+            A unicode string (:py:class:`unicode`)
-    -   :class:`datetime.datetime`
+
-    -   :class:`datetime.time`
+    -   .. wsme:type:: int
+    
+            An integer (:py:class:`int`)
+
+    -   .. wsme:type:: float
+    
+            A float (:py:class:`float`)
+
+    -   .. wsme:type:: bool
+    
+            A boolean (:py:class:`bool`)
+
+    -   .. wsme:type:: Decimal
+    
+            A fixed-width decimal (:py:class:`decimal.Decimal`)
+
+    -   .. wsme:type:: date
+            
+            A date (:py:class:`datetime.date`)
+
+    -   .. wsme:type:: datetime
+
+            A date and time (:py:class:`datetime.datetime`)
+
+    -   .. wsme:type:: time
+    
+            A time (:py:class:`datetime.time`)
 
     -   Arrays -- This is a special case. When stating a list
         datatype, always state its content type as the unique element
@@ -30,7 +56,15 @@ The native types are :
                 def getlist(self):
                     return ['a', 'b', 'c']
 
-There are other types that are supported out of the boxe, see
+    -   Dictionnaries -- Statically typed mapping are allowed. When exposing
+        a dictionnary datatype, you can specify the key and value types,
+        with a restriction on the key value that must be a 'pod' type.
+        Example::
+
+            class SomeType(object):
+                amap = {str: SomeOthertype}
+
+There are other types that are supported out of the box, see
 the :ref:`pre-defined-user-types`.
 
 User types

wsme/sphinxext.py

@@ -100,9 +100,13 @@ class TypeDirective(PyClasslike):
         return _('%s (webservice type)') % name_cls[0]
 
     def add_target_and_index(self, name_cls, sig, signode):
-        print name_cls, sig, signode
         ret = super(TypeDirective, self).add_target_and_index(name_cls, sig, signode)
-        print self.indexnode
+        name = name_cls[0]
+        types = self.env.domaindata['wsme']['types']
+        if name in types:
+            self.state_machine.reporter.warning(
+                'duplicate type description of %s ' % name)
+        types[name] = self.env.docname
         return ret
 
 
@@ -127,7 +131,7 @@ class TypeDocumenter(autodoc.ClassDocumenter):
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):
         # we don't want to be automaticaly used
-        # TODO check if the member is registered a an exposed type
+        # TODO check if the member is registered an an exposed type
         return False
 
     def format_name(self):
@@ -396,11 +400,19 @@ class WSMEDomain(Domain):
         'types': {},  # fullname -> docname
     }
 
+    def clear_doc(self, docname):
+        for name, value in self.data['types'].items():
+            if value == docname:
+                del self.data['types'][name]
+
+
     def resolve_xref(self, env, fromdocname, builder,
                      type, target, node, contnode):
-        print "Target: ", target, node
+        if target not in self.data['types']:
+            return None
+        todocname = self.data['types'][target]
         return make_refnode(
-            builder, fromdocname, fromdocname, target, contnode, target)
+            builder, fromdocname, todocname, target, contnode, target)
 
 
 def setup(app):