ftp tests, and doc refactor

Author: willmcgugan

.gitignore

@@ -1,3 +1,5 @@
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

docs/source/builtin.rst

@@ -4,9 +4,9 @@ Builtin Filesystems
 .. toctree::
    :maxdepth: 3
 
-   ftpfs.rst
-   memoryfs.rst
-   mountfs.rst
-   multifs.rst
-   osfs.rst
-   subfs.rst
+   reference/ftpfs.rst
+   reference/memoryfs.rst
+   reference/mountfs.rst
+   reference/multifs.rst
+   reference/osfs.rst
+   reference/subfs.rst

docs/source/guide.rst

@@ -1,5 +1,5 @@
-PyFilesystem Guide
-==================
+Guide
+=====
 
 The PyFilesytem interface simplifies most aspects of working with files and directories, even for quite simple operations. This guide covers how to work with PyFilesystem objects.
 
@@ -145,6 +145,21 @@ The :class:`fs.base.FS.makedir` and :class:`fs.base.FS.makedirs` methods also re
 
 Working with ``SubFS`` objects means that you can generally avoid writing much path manipulation code, which tends to be error prone.
 
+Walking
+~~~~~~~
+
+Often you will need to scan the files in a given directory, and any sub-directories. This is known as *walking* the filesystem.
+
+Here's how you would print the paths to all your Python files in your home-directory (and sub-directories)::
+
+    >>> from fs import open_fs
+    >>> from fs import walk
+    >>> home_fs = open_fs(~/)
+    >>> for path in walk(home_fs, wildcards=['*.py']):
+    ...     print(path)
+
+This might take a while to run, if you have a lot of Python code!
+
 Working with Files
 ~~~~~~~~~~~~~~~~~~
 

docs/source/reference.rst

@@ -4,13 +4,13 @@ Reference
 .. toctree::
    :maxdepth: 3
 
-   base.rst
-   copy.rst
-   errors.rst
-   enums.rst
-   info_objects.rst
-   move.rst
-   opener.rst
-   path.rst
-   tree.rst
-   walk.rst
+   reference/base.rst
+   reference/copy.rst
+   reference/errors.rst
+   reference/enums.rst
+   reference/info_objects.rst
+   reference/move.rst
+   reference/opener.rst
+   reference/path.rst
+   reference/tree.rst
+   reference/walk.rst