Update docs for tostring

docs/api/xmlstream/index.rst

@@ -10,3 +10,4 @@ xmlstream
 .. toctree::
 
     stanzabase
+    tostring

docs/api/xmlstream/stanzabase.rst

@@ -1,3 +1,5 @@
+.. _stanzabase:
+
 ==========
 stanzabase
 ==========

docs/api/xmlstream/tostring.rst

@@ -0,0 +1,17 @@
+========
+tostring
+========
+
+.. module:: sleekxmpp.xmlstream.tostring
+
+.. _tostring:
+
+XML Serialization
+-----------------
+
+.. autofunction:: tostring
+
+Escaping Special Characters
+---------------------------
+
+.. autofunction:: xml_escape

docs/index.rst

@@ -12,16 +12,8 @@ SleekXMPP
     ``master`` branch, while the latest development version is in the
     ``develop`` branch.
 
-    **Stable Releases**
+    **Latest Stable Release**
         - `1.0 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_  
-        - `1.0 RC2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC2>`_ 
-        - `1.0 RC1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC1>`_  
-        - `1.0 Beta6.1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta6.1>`_  
-        - `1.0 Beta5 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta5>`_
-        - `1.0 Beta4 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta4>`_
-        - `1.0 Beta3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta3>`_
-        - `1.0 Beta2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta2>`_
-        - `1.0 Beta1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta1>`_
 
     **Develop Releases**
         - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
@@ -90,7 +82,7 @@ Tutorials, FAQs, and How To Guides
     faq
     xeps
     xmpp_tdg
-    create_stanzas
+    howto/stanzas
     create_plugin
     features
     sasl
@@ -119,7 +111,7 @@ API Reference
     event_index
     api/clientxmpp
     api/basexmpp
-    api/xmlstream
+    api/xmlstream/index
 
 Additional Info
 ---------------

sleekxmpp/xmlstream/stanzabase.py

@@ -1071,6 +1071,8 @@ class ElementBase(object):
     def __str__(self, top_level_ns=True):
         """Return a string serialization of the underlying XML object.
 
+        .. seealso:: :ref:`tostring`
+
         :param bool top_level_ns: Display the top-most namespace.
                                   Defaults to True.
         """

sleekxmpp/xmlstream/tostring.py

@@ -1,9 +1,16 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
+    sleekxmpp.xmlstream.tostring
-    Copyright (C) 2010  Nathanael C. Fritz
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-    This file is part of SleekXMPP.
 
-    See the file LICENSE for copying permission.
+    This module converts XML objects into Unicode strings and
+    intelligently includes namespaces only when necessary to
+    keep the output readable.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 import sys
@@ -14,26 +21,28 @@ if sys.version_info < (3, 0):
 
 def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
              outbuffer='', top_level=False):
-    """
+    """Serialize an XML object to a Unicode string.
-    Serialize an XML object to a Unicode string.
 
-    If namespaces are provided using xmlns or stanza_ns, then elements
+    If namespaces are provided using ``xmlns`` or ``stanza_ns``, then
-    that use those namespaces will not include the xmlns attribute in
+    elements that use those namespaces will not include the xmlns attribute
-    the output.
+    in the output.
 
-    Arguments:
+    :param XML xml: The XML object to serialize. If the value is ``None``,
-        xml       -- The XML object to serialize. If the value is None,
                     then the XML object contained in this stanza
                     object will be used.
-        xmlns     -- Optional namespace of an element wrapping the XML
+    :param string xmlns: Optional namespace of an element wrapping the XML
                          object.
-        stanza_ns -- The namespace of the stanza object that contains
+    :param string stanza_ns: The namespace of the stanza object that contains
                              the XML object.
-        stream    -- The XML stream that generated the XML object.
+    :param stream: The XML stream that generated the XML object.
-        outbuffer -- Optional buffer for storing serializations during
+    :param string outbuffer: Optional buffer for storing serializations
-                     recursive calls.
+                             during recursive calls.
-        top_level -- Indicates that the element is the outermost
+    :param bool top_level: Indicates that the element is the outermost
                            element.
+
+    :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+
+    :rtype: Unicode string
     """
     # Add previous results to the start of the output.
     output = [outbuffer]
@@ -102,11 +111,9 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
 
 
 def xml_escape(text):
-    """
+    """Convert special characters in XML to escape sequences.
-    Convert special characters in XML to escape sequences.
 
-    Arguments:
+    :param string text: The XML text to convert.
-        text -- The XML text to convert.
     """
     if sys.version_info < (3, 0):
         if type(text) != types.UnicodeType: