Merged sphinx-docstrings-24: Convert docstrings to sphinx/rst format …

…and enable automatic API documentation generation

doc/conf.py

@@ -17,6 +17,10 @@
 # General configuration
 # ---------------------
 
+# 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']
+
 # Paths that contain templates, relative to this directory.
 templates_path = ['html']
 
@@ -44,8 +48,8 @@
 
 # We look for the __init__.py file in the current Plasma source tree
 # and replace the values accordingly.
-release = '.'.join(map(lambda x: str(x), plasma.__version__))
-version = release[:3]
+from plasma.version import version
+release = version
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/html/indexcontent.html

@@ -28,7 +28,7 @@
 
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("api/index") }}">Global Module Index</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Global Module Index</a><br/>
          <span class="linkdescr">Quick access to all modules</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
          <span class="linkdescr">Search this documentation</span></p>

plasma/__init__.py

@@ -2,22 +2,13 @@
 # See LICENSE.txt for details.
 
 """
-B{Plasma} is a Python implementation of Flex Messaging and Remoting.
+*Plasma* is a Python implementation of Flex Messaging and Remoting.
 
-@copyright: Copyright (c) 2009 The Plasma Project. All Rights Reserved.
+:copyright: Copyright (c) 2009 The Plasma Project. All Rights Reserved.
 @contact: U{plasma-users@plasmads.org<mailto:plasma-users@plasmads.org>}
 @see: U{http://plasmads.org}
 
 @since: September 2009
 @version: 0.1a
 @status: Pre-Alpha
 """
-
-
-__all__ = [
-    '__version__'
-]
-
-
-#: Plasma version number.
-__version__ = (0, 1, 'alpha')

plasma/flex/__init__.py

@@ -4,5 +4,6 @@
 """
 Flex Compatibility.
 
-@since: 0.1
+.. versionadded:: 0.1
+
 """

plasma/flex/data/__init__.py

@@ -2,7 +2,8 @@
 # See LICENSE.txt for details.
 
 """
-Support for C{flex.data.messages}.
+Support for `flex.data.messages`.
+
+.. versionadded:: 0.1
 
-@since: 0.1
 """

plasma/flex/data/messages.py

@@ -7,7 +7,8 @@
 This module contains the message classes used with Flex Data Management
 Service.
 
-@since: 0.1
+.. versionadded:: 0.1
+
 """
 
 
@@ -25,23 +26,25 @@
 
 class DataMessage(messages.AsyncMessage):
     """
-    I am used to transport an operation that occured on a managed object
-    or collection.
+    This message is used to transport an operation that occured on a managed
+    object or collection.
 
     This class of message is transmitted between clients subscribed to a
     remote destination as well as between server nodes within a cluster.
     The payload of this message describes all of the relevant details of
     the operation. This information is used to replicate updates and detect
     conflicts.
 
-    @ivar identity: Provides access to the identity map which defines the
-        unique identity of the item affected by this DataMessage (relevant for
-        create/update/delete but not fill operations).
-    @ivar operation: Provides access to the operation/command of this
-        DataMessage. Operations indicate how the remote destination should
+    :ivar identity: Provides access to the identity map which defines the
+        unique identity of the item affected by this `DataMessage`
+        (relevant for create/update/delete but not fill operations).
+    :ivar operation: Provides access to the operation/command of this
+        `DataMessage`. Operations indicate how the remote destination should
         process this message.
-    @see: U{DataMessage on Livedocs
-    <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/DataMessage.html>}
+    
+    .. seealso:: `DataMessage on Livedocs
+        <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/DataMessage.html>`_
+
     """
 
     def __init__(self, **kwargs):
@@ -53,16 +56,17 @@ def __init__(self, **kwargs):
 
 class SequencedMessage(messages.AcknowledgeMessage):
     """
-    Response to L{DataMessage} requests.
+    Response to :class:`DataMessage` requests.
 
-    @ivar sequenceId: Unique identifier for a sequence within a remote
+    :ivar sequenceId: Unique identifier for a sequence within a remote
         destination. This value is only unique for the endpoint and
         destination contacted.
-    @ivar sequenceProxies: ???
-    @ivar sequenceSize: How many items reside in the remote sequence.
+    :ivar sequenceProxies: ???
+    :ivar sequenceSize: How many items reside in the remote sequence.
+
+    .. seealso:: `SequencedMessage on Livedocs
+        <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/SequencedMessage.html>`_
 
-    @see: U{SequencedMessage on Livedocs
-    <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/SequencedMessage.html>}
     """
 
     def __init__(self, **kwargs):
@@ -78,14 +82,16 @@ def __init__(self, **kwargs):
 
 class PagedMessage(SequencedMessage):
     """
-    This messsage provides information about a partial sequence result.
+    This message provides information about a partial sequence result.
 
-    @ivar pageCount: Provides access to the number of total pages in a
+    :ivar pageCount: Provides access to the number of total pages in a
         sequence based on the current page size.
-    @ivar pageIndex: Provides access to the index of the current page in a
+    :ivar pageIndex: Provides access to the index of the current page in a
         sequence.
-    @see: U{PagedMessage on Livedocs
-    <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/PagedMessage.html>}
+
+    .. seealso:: `PagedMessage on Livedocs
+        <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/PagedMessage.html>`_
+
     """
 
     def __init__(self, **kwargs):
@@ -101,16 +107,17 @@ class DataErrorMessage(messages.ErrorMessage):
     occurs.
 
     This message provides the conflict information in addition to
-    the L{ErrorMessage<plasma.flex.messaging.ErrorMessage>} information.
+    the :class:`~plasma.flex.messaging.ErrorMessage` information.
 
-    @ivar cause: The client originated message which caused the conflict.
-    @ivar propertyNames: A list of properties that were found to be
+    :ivar cause: The client originated message which caused the conflict.
+    :ivar propertyNames: A list of properties that were found to be
         conflicting between the client and server objects.
-    @ivar serverObject: The value that the server had for the object with the
+    :ivar serverObject: The value that the server had for the object with the
         conflicting properties.
 
-    @see: U{DataErrorMessage on Livedocs
-    <http://livedocs.adobe.com/flex/201/langref/mx/data/messages/DataErrorMessage.html>}
+    .. seealso:: `DataErrorMessage on Livedocs
+        http://livedocs.adobe.com/flex/201/langref/mx/data/messages/DataErrorMessage.html>`_
+
     """
 
     def __init__(self, **kwargs):

plasma/flex/graphics.py

@@ -2,31 +2,33 @@
 # See LICENSE.txt for details.
 
 """
-Support for C{flex.graphics} packages.
+Support for `flex.graphics` packages.
+
+.. versionadded:: 0.1
 
-@since: 0.1
 """
 
 import pyamf
 
 
 class ImageSnapshot(object):
     """
-    This class corresponds to mx.graphics.ImageSnapshot on the client. Clients
-    may choose to capture images and send them to the server via a
+    This class corresponds to `mx.graphics.ImageSnapshot` on the client.
+    Clients may choose to capture images and send them to the server via a
     RemoteObject call.
 
-    @ivar contentType:  The content type for the image encoding format that
+    :ivar contentType:  The content type for the image encoding format that
         was used to capture this snapshot.
-    @type contentType: C{str}
-    @ivar width: The image width in pixels.
-    @type width: C{int}
-    @ivar height: The image height in pixels.
-    @type height: C{int}
-    @ivar properties: Additional properties of the image.
-    @type properties: C{dict}
-    @ivar data: The encoded data representing the image snapshot.
-    @type data: C{file} object
+    :type contentType: `str`
+    :ivar width: The image width in pixels.
+    :type width: `int`
+    :ivar height: The image height in pixels.
+    :type height: `int`
+    :ivar properties: Additional properties of the image.
+    :type properties: `dict`
+    :ivar data: The encoded data representing the image snapshot.
+    :type data: `file` object
+
     """
 
     def __init__(self, **kwargs):

plasma/flex/messaging/__init__.py

@@ -2,7 +2,8 @@
 # See LICENSE.txt for details.
 
 """
-Support for C{flex.messaging} namespace.
+Support for `flex.messaging` namespace.
+
+.. versionadded:: 0.1
 
-@since: 0.1
 """