Doc fixes

git-svn-id: http://pyfilesystem.googlecode.com/svn/trunk@651 67cdc799-7952-0410-af00-57a81ceafa0f

14 files changed, 44 insertions, 45 deletions

diff --git a/docs/base.rst b/docs/base.rst
index 86398a0..835c61d 100644
--- a/docs/base.rst
+++ b/docs/base.rst
@@ -6,7 +6,7 @@ This module contains the basic FS interface and a number of other essential inte
 fs.base.FS
 ----------
 
-All Filesystem objects inherit from this class,
+All Filesystem objects inherit from this class.
 
 .. autoclass:: fs.base.FS
     :members:
@@ -14,7 +14,7 @@ All Filesystem objects inherit from this class,
 fs.base.SubFS
 -------------
 
-A SubFS is an FS implementation that represents a directory on another Filesystem. When you use the `opendir` method it will return a SubFS instance. You should not need to instantiate a SubFS directly.
+A SubFS is an FS implementation that represents a directory on another Filesystem. When you use the :meth:`fs.base.FS.opendir` method it will return a SubFS instance. You should not need to instantiate a SubFS directly.
 
 For example::
 
@@ -28,7 +28,7 @@ fs.base.NullFile
 
 A NullFile is a file-like object with no functionality. It is used in situations where a file-like object is required but the caller doesn't have any data to read or write.
 
-The `safeopen` method returns an NullFile instance, which can reduce error-handling code.
+The :meth:`fs.base.FS.safeopen` method returns an NullFile instance, which can reduce error-handling code.
 
 For example, the following code may be written to append some text to a log file::
 
@@ -44,5 +44,5 @@ This could be re-written using the `safeopen` method::
 
     myfs.safeopen('log.txt', 'a').writeline('operation successful!')
 
-If the file doesn't exist then the call to writeline will be a null-operation (i.e. not do anything)
+If the file doesn't exist then the call to writeline will be a null-operation (i.e. not do anything).
 
diff --git a/docs/commands.rst b/docs/commands.rst
index 770bbc5..2b15f20 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -18,17 +18,19 @@ For example, the following uses a custom opener to list the contents of a direct
 
 	fsls --fs mypackage.mymodule.myfs.MyFSOpener myfs://127.0.0.1
 	
+	
 Listing Supported Filesystems
 -----------------------------
 
-All of the command line applications support the `--listopeners` switch, which lists all available installed openers::
+All of the command line applications support the ``--listopeners`` switch, which lists all available installed openers::
 
 	fsls --listopeners
 
+
 fsls
 ----
 
-Lists the contents of a directory, similar to the `ls` command, e.g.::
+Lists the contents of a directory, similar to the ``ls`` command, e.g.::
 
 	fsls	
 	fsls ../
diff --git a/docs/concepts.rst b/docs/concepts.rst
index 297ffa7..63bb1d5 100644
--- a/docs/concepts.rst
+++ b/docs/concepts.rst
@@ -71,7 +71,7 @@ For example::
 	u'/home/will/test.txt'
 
 Not all FS implementation will map to a valid system path (e.g. the FTP FS object).
-If you call :meth:`~fs.base.FS.getsyspath` on such FS objects you will either get a :class:`~fs.errors.NoSysPathError` exception or a return value of ``None``, if you call ``getsyspath`` with `allow_none=True`.
+If you call :meth:`~fs.base.FS.getsyspath` on such FS objects you will either get a :class:`~fs.errors.NoSysPathError` exception or a return value of ``None``, if you call ``getsyspath`` with ``allow_none=True``.
 
 Errors
 ------
@@ -89,4 +89,4 @@ PyFilesystem converts all exceptions to a common type, so that you need only wri
 	    return open(self.getsyspath(path), mode, kwargs.get("buffering", -1))
 	fs.errors.ResourceNotFoundError: Resource not found: doesnotexist.txt
 
-All PyFilesystem exceptions are derived from :class:`fs.errors.FSError`, so you may use that if you want to catch all possible exceptions.
+All PyFilesystem exceptions are derived from :class:`fs.errors.FSError`, so you may use that if you want to catch all possible filesystem related exceptions.
diff --git a/docs/expose.rst b/docs/expose.rst
index 0e50274..31e3d86 100644
--- a/docs/expose.rst
+++ b/docs/expose.rst
@@ -1,7 +1,7 @@
 Exposing FS objects
 ===================
 
-The ``fs.expose`` module offers a number of ways of making an FS implementation available over an internet connection, or to other processes on the system. 
+The ``fs.expose`` module offers a number of ways of making an FS implementation available over an Internet connection, or to other processes on the system. 
 
 
 FUSE
diff --git a/docs/ftpfs.rst b/docs/ftpfs.rst
index fa7f98c..1164d78 100644
--- a/docs/ftpfs.rst
+++ b/docs/ftpfs.rst
@@ -1,2 +1,2 @@
-.. automodule:: fs.ftpfs
+.. autoclass:: fs.ftpfs.FTPFS		
     :members:
\ No newline at end of file
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index 58cbfe3..83299fd 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -1,7 +1,7 @@
 Getting Started
 ===============
 
-PyFilesystem is a Python-only module and can be installed with easy_install or by source. PyFilesystem is known to work on Linux, Mac and OSX.
+PyFilesystem is a Python-only module and can be installed with easy_install or from source. PyFilesystem is known to work on Linux, Mac and OSX.
 
 Installing
 ----------
@@ -30,10 +30,10 @@ Prerequisites
 -------------
 
 PyFilesystem requires at least **Python 2.5**. There are a few other dependencies if you want to use some of the more advanced filesystem interfaces, but for basic use all that is needed is the Python standard library.
-
-    * wxPython (required for fs.browsewin) http://www.wxpython.org/
-    * Boto (required for fs.s3fs) http://code.google.com/p/boto/
-    * Paramikio (required for fs.ftpfs) http://www.lag.net/paramiko/    
+    
+    * Boto (required for :mod:`fs.s3fs`) http://code.google.com/p/boto/
+    * Paramikio (required for :mod:`fs.ftpfs`) http://www.lag.net/paramiko/
+    * wxPython (required for :mod:`fs.browsewin`) http://www.wxpython.org/    
 
 
 Quick Examples
diff --git a/docs/implementersguide.rst b/docs/implementersguide.rst
index c7385fd..3dc7f6e 100644
--- a/docs/implementersguide.rst
+++ b/docs/implementersguide.rst
@@ -9,9 +9,9 @@ With a little care, you can write a wrapper for your filesystem that allows it t
 To create a working PyFilesystem interface, derive a class from :py:class:`fs.base.FS` and implement the 9 :ref:`essential-methods`.
 The base class uses these essential methods as a starting point for providing a lot of extra functionality,
 but in some cases the default implementation may not be the most efficient.
-For example, most filesystems have some atomic way of moving a file without having to copy data,
-whereas the default implementation of :meth:`~fs.base.FS.move` method must copy all the bytes in the file.
-Although any of the :ref:`non-essential-methods` may be overriden, efficient versions of the following methods will have the greatest impact on performance:     
+For example, most filesystems have an atomic way of moving a file from one location to another without having to copy data,
+whereas the default implementation of :meth:`~fs.base.FS.move` method must copy all the bytes in the source file to the destination file.
+Any of the :ref:`non-essential-methods` may be overriden, but efficient custom versions of the following methods will have the greatest impact on performance:     
 
 	* :meth:`~fs.base.FS.copy` copy a file
 	* :meth:`~fs.base.FS.copydir` copy a directory
@@ -20,7 +20,7 @@ Although any of the :ref:`non-essential-methods` may be overriden, efficient ver
 	* :meth:`~fs.base.FS.move` move a file
 	* :meth:`~fs.base.FS.movedir` move a directory
 
-For network based filesystems (i.e. where the physical data is pulled from a network),
+For network based filesystems (i.e. where the physical data is pulled over a network),
 there are a few methods which can reduce the number of round trips to the server,
 if an efficient implementation is provided:
 	
@@ -46,7 +46,7 @@ but this shouldn't prevent it from working with more generic code.
 If specific exceptions need to be translated in to an equivalent FSError,
 pass the original exception class to the FSError constructor with the 'details' keyword argument.
 
-For example, the following translates some ficticious exception in to an FS exception,
+For example, the following translates some fictitious exception in to an FSError exception,
 and passes the original exception as an argument.::
 
     try:
@@ -75,7 +75,7 @@ Implementations are also free to reserve a dotted namespace notation for themsel
 If you do this, please avoid generic terms as they may conflict with existing or future implementations.
 For example ``"bobs_ftpfs.author"``, rather than ``"ftpfs.author"``.
 
-If your meta values are static, i.e. they never change, then create a dictionary class attribute called ``_meta`` in your implementation that contains all the meta keys, values. 
+If your meta values are static, i.e. they never change, then create a dictionary class attribute called ``_meta`` in your implementation that contains all the meta keys and values. 
 The default ``getmeta`` implementation will pull the meta values from this dictionary.
 
 .. _essential-methods:
diff --git a/docs/introduction.rst b/docs/introduction.rst
index af2795b..7f1ddd4 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -28,4 +28,3 @@ Discussion Group
 
 There is also a discussion group for PyFilesystem: http://groups.google.com/group/pyfilesystem-discussion
 
-
diff --git a/fs/base.py b/fs/base.py
index d7b75d4..fef2906 100644
--- a/fs/base.py
+++ b/fs/base.py
@@ -235,9 +235,10 @@ class FS(object):
          * *atomic.rename* True if rename is an atomic operation, (and not implemented as a copy followed by a delete)
          * *atomic.setcontents* True if the implementation supports setting the contents of a file as an atomic operation (without opening a file)        
          * *free_space* The free space (in bytes) available on the file system   
-         * *total_space* The total space (in bytes) available on the file system   
+         * *total_space* The total space (in bytes) available on the file system
+         * *virtual* True if the filesystem defers to other filesystems
         
-        FS implementations may expose non-generic meta data through a self-named namespace. e.g. ``somefs.some_meta``
+        FS implementations may expose non-generic meta data through a self-named namespace. e.g. ``"somefs.some_meta"``
         
         Since no meta value is guaranteed to exist, it is advisable to always supply a
         default value to ``getmeta``.   
diff --git a/fs/ftpfs.py b/fs/ftpfs.py
index 9a5ec70..44d6120 100644
--- a/fs/ftpfs.py
+++ b/fs/ftpfs.py
@@ -813,10 +813,8 @@ class FTPFS(FS):
               'file.read_and_write' : False,
               }
 
-    def __init__(self, host='', user='', passwd='', acct='', timeout=_GLOBAL_DEFAULT_TIMEOUT,
-                 port=21,
-                 dircache=True):
-        """ Connect to a FTP server.
+    def __init__(self, host='', user='', passwd='', acct='', timeout=_GLOBAL_DEFAULT_TIMEOUT, port=21, dircache=True):
+        """Connect to a FTP server.
         
         :param host: Host to connect to
         :param user: Username, or a blank string for anonymous
@@ -825,10 +823,9 @@ class FTPFS(FS):
         :param timeout: Timeout in seconds
         :param port: Port to connection (default is 21)
         :param dircache: If True then directory information will be cached,
-        which will speed up operations such as getinfo, isdir, isfile, but
-        changes to the ftp file structure will not be visible until
-        `~fs.ftpfs.FTPFS.clear_dircache` is called        
-        :param dircache: If True directory information will be cached for fast access        
+            speeding up operations such as `getinfo`, `isdir`, `isfile`, but
+            changes to the ftp file structure will not be visible until
+            :meth:`~fs.ftpfs.FTPFS.clear_dircache` is called                
 
         """
 
diff --git a/fs/mountfs.py b/fs/mountfs.py
index 7f6a6cf..d4f4ce4 100644
--- a/fs/mountfs.py
+++ b/fs/mountfs.py
@@ -396,7 +396,7 @@ class MountFS(FS):
         """Mounts a single file path.
         
         :param path: A path within the MountFS
-        :param open_Callable: A callable that returns a file-like object
+        :param open_callable: A callable that returns a file-like object
         :param info_callable: A callable that returns a dictionary with information regarding the file-like object
         
         """
diff --git a/fs/utils.py b/fs/utils.py
index 48f39aa..016ce71 100644
--- a/fs/utils.py
+++ b/fs/utils.py
@@ -18,7 +18,7 @@ import os
 import sys
 import stat
 from fs.mountfs import MountFS
-from fs.path import pathjoin, pathsplit
+from fs.path import pathjoin
 from fs.errors import DestinationExistsError
 from fs.base import FS
 
@@ -32,7 +32,7 @@ def copyfile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
     :param src_path: -- Source path
     :param dst_fs: Destination filesystem object
     :param dst_path: Destination filesystem object
-    :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+    :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
 
     """
     
@@ -76,7 +76,7 @@ def copyfile_non_atomic(src_fs, src_path, dst_fs, dst_path, overwrite=True, chun
     :param src_path: -- Source path
     :param dst_fs: Destination filesystem object
     :param dst_path: Destination filesystem object
-    :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+    :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
     
     """
     
@@ -109,7 +109,7 @@ def movefile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
     :param src_path: Source path
     :param dst_fs: Destination filesystem object
     :param dst_path: Destination filesystem object
-    :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+    :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
 
     """
     src_syspath = src_fs.getsyspath(src_path, allow_none=True)
@@ -151,13 +151,13 @@ def movefile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
 
 
 def movefile_non_atomic(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1024):
-    """A non atomic version of movefile (wont block other threads using src_fs or dst_fs
+    """A non atomic version of movefile (wont block other threads using src_fs or dst_fs)
 
     :param src_fs: Source filesystem object
     :param src_path: Source path
     :param dst_fs: Destination filesystem object
     :param dst_path: Destination filesystem object
-    :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+    :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
 
     """    
 
diff --git a/fs/watch.py b/fs/watch.py
index be4b4a1..6ba8a28 100644
--- a/fs/watch.py
+++ b/fs/watch.py
@@ -10,13 +10,13 @@ simulate such an ability on top of an ordinary FS object.
 
 An FS object that wants to be "watchable" must provide the following methods:
 
-  * add_watcher(callback,path="/",events=None,recursive=True)
+  * ``add_watcher(callback,path="/",events=None,recursive=True)``
 
       Request that the given callback be executed in response to changes 
       to the given path.  A specific set of change events can be specified.
       This method returns a Watcher object.
 
-  * del_watcher(watcher_or_callback)
+  * ``del_watcher(watcher_or_callback)``
 
       Remove the given watcher object, or any watchers associated with
       the given callback.
diff --git a/fs/xattrs.py b/fs/xattrs.py
index 73b438b..1089455 100644
--- a/fs/xattrs.py
+++ b/fs/xattrs.py
@@ -11,10 +11,10 @@ extended attributes on top of an ordinary FS.
 FS instances offering extended attribute support must provide the following
 methods:
 
-  * getxattr(path,name) Get the named attribute for the given path, or None if it does not exist
-  * setxattr(path,name,value) Set the named attribute for the given path to the given value
-  * delxattr(path,name) Delete the named attribute for the given path, raising KeyError if it does not exist
-  * listxattrs(path) Iterate over all stored attribute names for the given path
+  * ``getxattr(path,name)`` Get the named attribute for the given path, or None if it does not exist
+  * ``setxattr(path,name,value)`` Set the named attribute for the given path to the given value
+  * ``delxattr(path,name)`` Delete the named attribute for the given path, raising KeyError if it does not exist
+  * ``listxattrs(path)`` Iterate over all stored attribute names for the given path
 
 If extended attributes are required by FS-consuming code, it should use the
 function 'ensure_xattrs'. This will interrogate an FS object to determine