Made a start on the docs

docs/commands.rst

+fs.commands
+===========
\ No newline at end of file

docs/conf.py

@@ -53,9 +53,9 @@ copyright = u'2009-2010, Will McGugan, Ryan Kelly'
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.0'
+release = '0.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -38,6 +38,7 @@ Code Documentation
    mountfs.rst
    multifs.rst
    osfs.rst
+   opener.rst
    path.rst
    remote.rst
    rpcfs.rst

docs/opener.rst

+
+.. automodule:: fs.opener
+    :members:
\ No newline at end of file

fs/opener.py

 """
-    fs.opener: open file systems from a FS url
+fs.opener
+=========
+
+Open filesystems via a URI.
+
+There are occasions when you want to specify a filesytem from the command line or in a config file.
+This module enables that functionality, and can return a FS object given a URI like syntax (http://commons.apache.org/vfs/filesystems.html).
+
+The `OpenerRegistry` class maps the protocol (file, ftp etc.) on to an Opener object, which returns an appropriate filesystem object and path.
+You can create a custom opener registry that opens just the filesystems you require, or use the opener registry defined here (also called `opener`) that can open any supported filesystem.
+The `parse` method of an `OpenerRegsitry` object returns a tuple of an FS object a path. Here's an example of how to use the default opener registry:: 
+
+    >>> from fs.opener import opener
+    >>> opener.parse('ftp://ftp.mozilla.org')
+    (<fs.ftpfs.FTPFS object at 0x96e66ec>, u'pub')
+    
+You can use use the `opendir` method, which just returns an FS object. In the example above, `opendir` will return a FS object for the directory `pub`::
+
+    >>> opener.opendir('ftp://ftp.mozilla.org/pub')
+    <SubFS: <FTPFS ftp.mozilla.org>/pub>
+    
+If you are just interested in a single file, use the `open` method of a registry which returns a file-like object, and has the same signature as FS objects and the `open` builtin::
+
+    >>> opener.open('ftp://ftp.mozilla.org/pub/README')
+    <fs.ftpfs._FTPFile object at 0x973764c>
+
+The `opendir` and `open` methods can also be imported from the top-level of this module for sake of convenience.
+To avoid shadowing the builtin `open` methd, they are named `fsopendir` and `fsopen`. Here's how you might import them::
+
+    from fs.opener import fsopendir, fsopen
+ 
+
 
 """
 
@@ -33,9 +64,11 @@ import re
 from urlparse import urlparse
 
 class OpenerError(Exception):
+    """The base exception thrown by openers"""
     pass
 
 class NoOpenerError(OpenerError):
+    """Thrown when there is no opener for the given protocol"""
     pass
 
 def _expand_syspath(path):
@@ -78,7 +111,7 @@ def _split_url_path(url):
 
 class OpenerRegistry(object):
      
-    """An opener stores a number of opener objects that are used to parse FS URLs"""
+    """An opener registry that  stores a number of opener objects used to parse FS URIs"""
 
     re_fs_url = re.compile(r'''
 ^
@@ -632,5 +665,3 @@ opener = OpenerRegistry([OSFSOpener,
 
 fsopen = opener.open
 fsopendir = opener.opendir
-
-    

fs/wrapfs/subfs.py

@@ -30,10 +30,11 @@ class SubFS(WrapFS):
         return abspath(normpath(path))[len(self.sub_dir):]
 
     def __str__(self):
-        return self.wrapped_fs.desc(self.sub_dir)        
+        #return self.wrapped_fs.desc(self.sub_dir)
+        return '<SubFS: %s%s>' % (self.wrapped_fs, self.sub_dir)
 
     def __unicode__(self):
-        return u'<SubFS: %s!%s>' % (self.wrapped_fs, self.sub_dir)        
+        return u'<SubFS: %s%s>' % (self.wrapped_fs, self.sub_dir)        
 
     def __repr__(self):
         return str(self)