More docs

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

3 files changed, 38 insertions, 1 deletions

diff --git a/docs/implementersguide.rst b/docs/implementersguide.rst
new file mode 100644
index 0000000..aa20f9d
--- /dev/null
+++ b/docs/implementersguide.rst
@@ -0,0 +1,30 @@
+A Guide For Filesystem Implementers 
+===================================
+
+PyFilesystems objects are designed to be as generic as possible and still expose as much functionality as possible.
+With a little care, you can write a wrapper for your filesystem that allows it to work interchangeably with any of the built-in FS classes and tools. 
+
+To create a working PyFilesystem interface, derive a class from :py:class:`fs.base.FS` and implement the 9 :ref:`essential-methods`.
+
+
+Filesystem Errors
+-----------------
+
+With the exception of the constuctor, FS methods should throw :class:`fs.errors.FSError` exceptions in preference to any specific exception classes,
+so that generic exception handling can be written.
+The constructor *may* throw a non-FSError exception, if no appropriate FSError exists.
+The rational for this is that creating an FS interface may require specific knowledge,
+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,
+and passes the original exception as an argument.::
+
+    try:
+        someapi.open(path, mode)
+    except someapi.UnableToOpen, e:
+        raise errors.ResourceNotFoundError(path=path, details=e)
+		
+Any code written to catch the generic error, can also retrieve the original exception if it contains additional information. 
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index b415571..241c58a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ Guide
    expose.rst
    utilities.rst
    commands.rst
+   implementersguide.rst
    
 Code Documentation
 ------------------
diff --git a/docs/interface.rst b/docs/interface.rst
index bf3ae9a..f39ed65 100644
--- a/docs/interface.rst
+++ b/docs/interface.rst
@@ -9,6 +9,8 @@ It may also be worthwhile implementing some of the non-essential methods, as the
 
 If the filesystem you are implementing maps paths to the native filesystem, be sure to implement :py:meth:`~fs.base.FS.getsyspath`. Doing so will improve performance, especially when copying / moving files between FS objects.
 
+.. _essential-methods:
+
 Essential Methods
 -----------------
 
@@ -25,6 +27,8 @@ The following methods are required for a minimal Filesystem interface:
     * :meth:`~fs.base.FS.getinfo` Return information about the path e.g. size, mtime
     
 
+.. _non-essential-methods:
+
 Non - Essential Methods
 -----------------------
 
@@ -46,10 +50,12 @@ The following methods have default implementations in :py:class:`fs.base.FS` and
     * :meth:`~fs.base.FS.move` Move a file to a new location        
     * :meth:`~fs.base.FS.movedir` Recursively move a directory to a new location
     * :meth:`~fs.base.FS.opendir` Opens a directory and returns an FS object that represents it
-    * :meth:`~fs.base.FS.safeopen` Like :meth:`~fs.base.open` but returns a NullFile if the file could not be opened
+    * :meth:`~fs.base.FS.safeopen` Like :meth:`~fs.base.FS.open` but returns a :class:`~fs.base.NullFile` if the file could not be opened
     * :meth:`~fs.base.FS.settimes` Sets the accessed and modified times of a path
 
 
+.. _utility-methods:
+
 Utility Methods
 ---------------