Merging new_data into master...finally.

Author: GraylinKim

docs/source/_static/deleteme

@@ -48,9 +48,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2'
+version = '0.3.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.2'
+release = '0.3.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -212,5 +212,5 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'sc2reader', u'sc2reader Documentation',
-     [u'Graylin Kim, Bas Peschier'], 1)
+     [u'Graylin Kim'], 1)
 ]

docs/source/conf.py

@@ -0,0 +1,117 @@
+sc2reader Documentation
+=====================================
+
+sc2reader is a library for extracting game information from Starcraft II
+replay files into a structured replay object. sc2reader aims to give anyone
+and everyone the power to construct their own tools and hack on their own
+Starcraft II projects under the open MIT license.
+
+This document is a work in progress and an attempt to document the use and
+configuration of sc2reader as well as the data that it makes available. I'll
+try to keep it up to date and fill out some of the missing sections as time
+goes on. While this document will hopefully give you an idea how sc2reader works
+there is no substitute for reading the source code. If you plan on seriously
+using the library please feel welcome to ask questions in #sc2reader on FreeNode
+(IRC) or on the `mailing list`_. I'd be happy to help you out.
+
+.. _mailing list: http://groups.google.com/group/sc2reader
+
+Use and Configuration
+=======================
+
+Basic Use
+-------------
+
+The sc2reader package itself can be configured and used to read replay files
+right out of the box! This lightweight approach to usage provides default
+options for full replay parsing so no configuration is necessary for normal use.
+
+read
+~~~~~~~~
+
+::
+
+    >>> import sc2reader
+    >>> sc2reader.read('test_replays/1.4.0.19679/36663.SC2Replay')
+    [<sc2reader.objects.Replay object at 0x944822c>]
+
+Notice that a list of Replay_ objects was returned. That is because the read
+function is always plural and will return a list regardless of how many replays
+it finds at the path that you send it.
+
+It works by (optionally) recursing through the specified path (if its a directory)
+and grabbing all files of the .SC2Replay file type and parsing them. Because of
+this, while the path you send it must always exist it is possible for the read_
+function to return an empty array of not files are found. This scanning process
+is fairly configurable by several of the available Options_.
+
+Because frequently you will be parsing only a single file or will be in an
+environment where you only have access to file or file-like objects, a read_file_
+function is available as well.
+
+read_file
+~~~~~~~~~~~~
+
+::
+
+    >>> import sc2reader
+    >>> replay = sc2reader.read_file('test_replays/1.4.0.19679/36663.SC2Replay')
+    >>> print "{0} on {1}, played on {2}".format(replay.type, replay.map, replay.date)
+    1v1 on Xel'Naga Caverns, played on 2011-09-21 02:49:47
+
+The read file function can accept either a path to a single file or a reference
+to a file-like object. A file-like object must implement the ``seek`` and
+``read`` methods to be valid. These two functions read_file_ and read_ provide
+the interface for constructing replays from file objects.
+
+
+configure
+~~~~~~~~~~~
+
+::
+
+    >>> import sc2reader
+    >>> sc2reader.configure(files=sc2reader.config.files.partial)
+    >>> replay = sc2reader.read_file('CustomMap.SC2Replay')
+
+The configure_ function can be used to change the default configuration of the
+replay parser and processor. This can be used to effect scanning of the file
+tree, the output and logging destination, and the fullness of the parsing. In
+the example above, we have restricted the file set to a partial parse and
+excluded the replay.game.events file from the parsing process. While sc2reader
+doesn't support custom games, by restricting the file set it can successfully
+read custom games to get non-event related information including summary game
+information as well as a general profile of the players.
+
+For one off configuration jobs though, sometimes its easier to pass the options
+in as keyword arguments to the read_ and read_file_ functions. This will leave
+the current sc2reader options untouched and won't affect future calls.
+
+::
+
+    >>> import sc2reader
+    >>> sc2reader.read(path, **options)
+    >>> sc2reader.read_file(fileobj, **options)
+
+
+Advanced Use
+--------------
+
+In addition to making the read_, read_file_, and configure_ methods available on
+the module, they are also available as part of an SC2Reader class with the same
+call signature. This can let you move easily between several different
+configurations as needed for different tasks.
+
+::
+
+    >>> from sc2reader import SC2Reader
+    >>> reader = SC2Reader(**options)
+    >>> reader.read_file('test_replays/1.4.0.19679/36663.SC2Replay')
+    <sc2reader.objects.Replay object at 0x944822c>
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`