Update tostring docs, plus more doc cleanup

docs/api/basexmpp.rst

@@ -1,5 +1,5 @@
 ========
-basexmpp
+BaseXMPP
 ========
 
 .. module:: sleekxmpp.basexmpp

docs/api/clientxmpp.rst

@@ -1,17 +1,8 @@
 ==========
-clientxmpp
+ClientXMPP
 ==========
 
 .. module:: sleekxmpp.clientxmpp
 
 .. autoclass:: ClientXMPP
-    
-    .. automethod:: connect
-
-    .. automethod:: register_feature
-
-    .. automethod:: get_roster
-
-    .. automethod:: update_roster
-
-    .. automethod:: del_roster_item
+    :members:

docs/api/componentxmpp.rst

@@ -0,0 +1,8 @@
+=============
+ComponentXMPP
+=============
+
+.. module:: sleekxmpp.componentxmpp
+
+.. autoclass:: ComponentXMPP
+    :members:

docs/api/xmlstream/stanzabase.rst

@@ -1,13 +1,13 @@
 .. _stanzabase:
 
-==========
-stanzabase
-==========
+==============
+Stanza Objects
+==============
 
 .. module:: sleekxmpp.xmlstream.stanzabase
 
-The :mod:`sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
-standard :mod:`xml.etree.cElementTree` module that makes working with XML
+The :mod:`~sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
+standard :mod:`~xml.etree.ElementTree` module that makes working with XML
 less painful. Instead of having to manually move up and down an element
 tree and insert subelements and attributes, you can interact with an object
 that behaves like a normal dictionary or JSON object, which silently maps
@@ -52,7 +52,7 @@ elements of the original XML chunk.
 .. seealso::
     :ref:`create-stanza-interfaces`.
 
-Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed
+Because the :mod:`~sleekxmpp.xmlstream.stanzabase` module was developed
 as part of an `XMPP <http://xmpp.org>`_ library, these chunks of XML are
 referred to as :term:`stanzas <stanza>`, and in SleekXMPP we refer to a
 subclass of :class:`ElementBase` which defines the interfaces needed for

docs/api/xmlstream/tostring.rst

@@ -1,17 +1,46 @@
-========
-tostring
-========
-
 .. module:: sleekxmpp.xmlstream.tostring
 
 .. _tostring:
 
 XML Serialization
------------------
+=================
+
+Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`,
+why not just use the built-in :func:`~xml.etree.ElementTree.tostring`
+method? The answer is that using that method produces ugly results when
+using namespaces. The :func:`tostring()` method used here intelligently
+hides namespaces when able and does not introduce excessive namespace
+prefixes::
+
+    >>> from sleekxmpp.xmlstream.tostring import tostring
+    >>> from xml.etree import cElementTree as ET
+    >>> xml = ET.fromstring('<foo xmlns="bar"><baz /></foo>')
+    >>> ET.tostring(xml)
+    '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>'
+    >>> tostring(xml)
+    '<foo xmlns="bar"><baz /></foo>'
+
+As a side effect of this namespace hiding, using :func:`tostring()` may
+produce unexpected results depending on how the :func:`tostring()` method
+is invoked. For example, when sending XML on the wire, the main XMPP
+stanzas with their namespace of ``jabber:client`` will not include the
+namespace because that is already declared by the stream header. But, if
+you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump
+it to the terminal, the ``jabber:client`` namespace will appear.
 
 .. autofunction:: tostring
 
 Escaping Special Characters
 ---------------------------
 
+In order to prevent errors when sending arbitrary text as the textual
+content of an XML element, certain characters must be escaped. These
+are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping
+mechanism is to replace those characters with their equivalent escape
+entities: ``&amp;``, ``&lt;``, ``&gt;``, ``&apos;``, and ``&quot;``.
+
+In the future, the use of CDATA sections may be allowed to reduce the
+size of escaped text or for when other XMPP processing agents do not
+undertand these entities.
+
 .. autofunction:: xml_escape

docs/conf.py

@@ -218,3 +218,5 @@ man_pages = [
     ('index', 'sleekxmpp', u'SleekXMPP Documentation',
      [u'Nathan Fritz, Lance Stout'], 1)
 ]
+
+intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 'python-objects.inv')}

docs/index.rst

@@ -110,8 +110,10 @@ API Reference
     
     event_index
     api/clientxmpp
+    api/componentxmpp
     api/basexmpp
-    api/xmlstream/index
+    api/xmlstream/stanzabase
+    api/xmlstream/tostring
 
 Additional Info
 ---------------

sleekxmpp/xmlstream/tostring.py

@@ -27,9 +27,7 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
     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 XML xml: The XML object to serialize.
     :param string xmlns: Optional namespace of an element wrapping the XML
                          object.
     :param string stanza_ns: The namespace of the stanza object that contains
@@ -40,6 +38,8 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
     :param bool top_level: Indicates that the element is the outermost
                            element.
 
+
+    :type xml: :py:class:`~xml.etree.ElementTree.Element`
     :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
 
     :rtype: Unicode string
@@ -114,6 +114,7 @@ def xml_escape(text):
     """Convert special characters in XML to escape sequences.
 
     :param string text: The XML text to convert.
+    :rtype: Unicode string
     """
     if sys.version_info < (3, 0):
         if type(text) != types.UnicodeType: