Lots of docs, some cosmetic changes

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

5 files changed, 32 insertions, 7 deletions

diff --git a/docs/contrib/index.rst b/docs/contrib/index.rst
index c55f8f9..5879b8e 100644
--- a/docs/contrib/index.rst
+++ b/docs/contrib/index.rst
@@ -1,5 +1,5 @@
 fs.contrib
-=========
+==========
 
 The ``fs.contrib`` module contains a number of filesystem implementations provided by third parties.
 
diff --git a/docs/index.rst b/docs/index.rst
index 80fcd74..0452d35 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,11 +17,13 @@ Guide
    introduction.rst
    getting_started.rst
    concepts.rst
+   opening.rst
    interface.rst
    filesystems.rst
    contrib.rst
    expose.rst
    utilities.rst
+   commands.rst
    
 Code Documentation
 ------------------
diff --git a/docs/interface.rst b/docs/interface.rst
index 0b4af59..bf3ae9a 100644
--- a/docs/interface.rst
+++ b/docs/interface.rst
@@ -3,11 +3,11 @@ Filesystem Interface
 
 It requires a relatively small number of methods to implement a working FS object.
 
-If you are looking to implement a working FS object, derive a class from fs.base.FS and implement the essential methods (below). Be sure to convert all exceptions to instances of :class:`fs.errors.FSError`.
+If you are looking to implement a working FS object, derive a class from :py:class:`fs.base.FS` and implement the essential methods (below). Be sure to convert all exceptions to instances of :class:`fs.errors.FSError`.
 
-It may also be worthwhile implementing some of the non-essential methods, as the default implementations may not be optimal. For example, the method :meth:`fs.base.FS.move` is implemeneted as a file copy followed by a delete, but many filesystems can move a file without copying data.
+It may also be worthwhile implementing some of the non-essential methods, as the default implementations may not be optimal. For example, the method :meth:`fs.base.FS.move` is implemented as a file copy followed by a delete, but many filesystems can move a file without copying data.
 
-If the filesystem you are implementing maps paths to the native filesystem, be sure to implement `getsyspath`. Doing so will improve performance, especialy when copying / moving files between FS objects.
+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
 -----------------
@@ -28,7 +28,7 @@ The following methods are required for a minimal Filesystem interface:
 Non - Essential Methods
 -----------------------
 
-The following methods have default implementations in fs.base.FS and aren't required for a functional FS interface. They may be overriden if an alternative implementation can be supplied:
+The following methods have default implementations in :py:class:`fs.base.FS` and aren't required for a functional FS interface. They may be overriden if an alternative implementation can be supplied:
 
     * :meth:`~fs.base.FS.copy` Copy a file to a new location
     * :meth:`~fs.base.FS.copydir` Recursively copy a directory to a new location
@@ -53,7 +53,7 @@ The following methods have default implementations in fs.base.FS and aren't requ
 Utility Methods
 ---------------
 
-The following members have implementations in fs.base.FS and will probably never require a non-default implementation, although there is nothing to prevent a derived class from implementing these:
+The following members have implementations in :py:class:`fs.base.FS` and will probably never require a non-default implementation, although there is nothing to prevent a derived class from implementing these:
 
     * :meth:`~fs.base.FS.createfile` Create a file with data
     * :meth:`~fs.base.FS.getcontents` Returns the contents of a file as a string
diff --git a/docs/opener.rst b/docs/opener.rst
index 32c123e..2ade5b6 100644
--- a/docs/opener.rst
+++ b/docs/opener.rst
@@ -1,3 +1,2 @@
-
 .. automodule:: fs.opener
     :members:
\ No newline at end of file
diff --git a/docs/opening.rst b/docs/opening.rst
new file mode 100644
index 0000000..5bfe120
--- /dev/null
+++ b/docs/opening.rst
@@ -0,0 +1,24 @@
+Opening Filesystems
+===================
+
+Generally, when you want to work with the files and directories of any of the supported filesytems,
+you create an instance of the appropriate class. For example, the following opens the directory /foo/bar::
+
+	from fs.osfs import OSFS
+	my_fs = OSFS('/foo/bar')
+
+This is fine if you know beforehand where the directory you want to work with is located, and on what medium.
+However, there are occasions where the location of the files may change at runtime or should be specified in a config file or from the command line.
+
+In these situations you can use an _opener_ which is a generic way of specifying a filesystem. For example, the following is equivalent to the code above::
+	
+	from fs.opener import fsopen
+	my_fs = fsopen('/foo/bar')
+
+The `fsopen` method takes a string that identifies the filesystem, but if called with a regular path, it will return an OSFS instance.
+To open a different kind of filesystem, you specify it with a URI like syntax. The following code opens an ftp filesystem rather than a directory on your harddrive::
+
+	from fs.opener import fsopen
+	my_fs = fsopen('ftp://example.org/foo/bar')
+
+For further information regarding filesystem openers see :doc:`opener`.
\ No newline at end of file