Update docs for tostring

6 files changed, 60 insertions, 39 deletions

diff --git a/docs/api/xmlstream.rst b/docs/api/xmlstream/index.rst
index 65200f66..22f9f3ff 100644
--- a/docs/api/xmlstream.rst
+++ b/docs/api/xmlstream/index.rst
@@ -10,3 +10,4 @@ xmlstream
 .. toctree::
 
     stanzabase
+    tostring
diff --git a/docs/api/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst
index 5a2c9a06..afed7655 100644
--- a/docs/api/stanzabase.rst
+++ b/docs/api/xmlstream/stanzabase.rst
@@ -1,3 +1,5 @@
+.. _stanzabase:
+
 ==========
 stanzabase
 ==========
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
new file mode 100644
index 00000000..038b7876
--- /dev/null
+++ b/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
diff --git a/docs/index.rst b/docs/index.rst
index 6898b506..525a479f 100644
--- a/docs/index.rst
+++ b/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
 ---------------
diff --git a/sleekxmpp/xmlstream/stanzabase.py b/sleekxmpp/xmlstream/stanzabase.py
index 2af5ec3c..6f27c361 100644
--- a/sleekxmpp/xmlstream/stanzabase.py
+++ b/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.
         """
diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py
index f9674b15..ed58049e 100644
--- a/sleekxmpp/xmlstream/tostring.py
+++ b/sleekxmpp/xmlstream/tostring.py
@@ -1,9 +1,16 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.tostring
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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.
-
-    If namespaces are provided using xmlns or stanza_ns, then elements
-    that use those namespaces will not include the xmlns attribute in
-    the output.
-
-    Arguments:
-        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
-                     object.
-        stanza_ns -- The namespace of the stanza object that contains
-                     the XML object.
-        stream    -- The XML stream that generated the XML object.
-        outbuffer -- Optional buffer for storing serializations during
-                     recursive calls.
-        top_level -- Indicates that the element is the outermost
-                     element.
+    """Serialize an XML object to a Unicode string.
+
+    If namespaces are provided using ``xmlns`` or ``stanza_ns``, then
+    elements that use those namespaces will not include the xmlns attribute
+    in the output.
+
+    :param XML xml: The XML object to serialize. If the value is ``None``,
+                    then the XML object contained in this stanza
+                    object will be used.
+    :param string xmlns: Optional namespace of an element wrapping the XML
+                         object.
+    :param string stanza_ns: The namespace of the stanza object that contains
+                             the XML object.
+    :param stream: The XML stream that generated the XML object.
+    :param string outbuffer: Optional buffer for storing serializations
+                             during recursive calls.
+    :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:
-        text -- The XML text to convert.
+    :param string text: The XML text to convert.
     """
     if sys.version_info < (3, 0):
         if type(text) != types.UnicodeType: