Update the documentation for the release

Author: GraylinKim

docs/source/index.rst

@@ -6,23 +6,27 @@ Thanks for choosing sc2reader for your Starcraft analysis needs.
 There is a pressing need in the SC2 community for better statistics, better
 analytics, better tools for organizing and searching replays. Better websites
 for sharing replays and hosting tournaments. These tools can't be created with
-out first being able to open up replay files and analyse the content within. That's why SC2Reader was built, to provide a solid foundation on which the next
+out first being able to open up replay files and analyse the content within.
+That's why SC2Reader was built, to provide a solid foundation on which the next
 generation of tools and websites can be built and benefit the community.
 
 So lets get you started right away! Through the linked tutorials and reference
 pages below we'll get you started building your own tools and systems in no
-time. Any questions, suggestions, or concerns should be posted to the sc2reader `mailing list`_. You can also pop on to our #sc2reader, our `IRC channel`_ on Freenode if you want to chat or need some live support.
+time. Any questions, suggestions, or concerns should be posted to the sc2reader
+`mailing list`_. You can also pop on to our #sc2reader, our `IRC channel`_ on
+Freenode if you want to chat or need some live support.
 
 .. _mailing list: http://groups.google.com/group/sc2reader
 .. _IRC Channel: http://webchat.freenode.net/?channels=#sc2reader
 
+
 Tutorials
 ---------------
 
 The best way to learn how to pick sc2Reader up and get started is probably by example. With that in mind, we've written up a series of tutorials on getting various simple tasks done with sc2reader; hopefully they can serve as a quick on ramp for you.
 
 * :doc:`tutorials/prettyprinter` (10-15 minutes)
-* :doc:`tutorials/actionlistener` (10-15 minutes)
+
 
 Reference Pages
 -----------------------
@@ -32,10 +36,10 @@ SC2 replays hold a ton of information. The following reference pages were put to
 .. toctree::
 
     sc2reader
-    mainstructures
-    supportstructures
-    listeners
-    processors
+    primaryresources
+    supportobjects
+    utilityclasses
+    plugins
 
 
 .. toctree::
@@ -44,8 +48,8 @@ SC2 replays hold a ton of information. The following reference pages were put to
     :glob:
 
     sc2reader
-    mainstructures
-    supportstructures
-    listeners
-    processors
-    tutorials/*
+    primaryresources
+    supportobjects
+    utilityclasses
+    plugins
+    tutorials/*

docs/source/mainstructures.rst

@@ -0,0 +1,59 @@
+Plugins
+=============
+
+A plugin is pretty much just a callable function or object that accepts a replay
+file as a single argument. sc2reader supports assignment of plugins to different
+resource types via the :meth:`SC2Factory.register_plugin` factory method.
+
+::
+
+    import sc2reader
+    from sc2reader.plugins.replay import APMTracker, SelectionTracker
+    sc2reader.register_plugin('Replay',APMTracker())
+    sc2reader.register_plugin('Replay',SelectionTracker())
+
+The order you register plugins is the order they are executed in so be careful to
+put register in the right order if you have dependencies between plugins.
+
+
+APMTracker
+----------------
+
+The APMTracker adds three simple fields based on a straight tally of non-camera
+player action events such as selections, abilities, and hotkeys.
+
+* ``player.aps`` = a dictionary of second => total actions in that second
+* ``player.apm`` = a dictionary of minute => total actions in that minute
+* ``player.avg_apm`` = Average APM as a float
+
+
+SelectionTracker
+--------------------
+
+The :class:`SelectionTracker` plugin simulates every person's selection at every
+frame in both the hotkey and active selection buffers. This selection information
+is stored in ``person.selection`` as a two dimensional array of lists.
+
+::
+
+    unit_list = replay.player[1].selection[frame][buffer]
+
+Where buffer is a hotkey 0-9 or 10 which represents the active selection.
+
+There are a number of known flaws with the current tracking algorithm and/or the
+source information on which it works:
+
+* Deaths are not recorded. A selected unit that dies will be deselected though.
+* Transformations are not recorded. A hotkey'd egg that hatches into 2 zerglings
+  will not register and the egg will stay hotkeyed until the hotkey is over
+  written. If the transformed unit is part of active selection the
+  selection/deslection is handled properly.
+
+To help expose these short comings a ``person.selection_errors`` tally is kept. An
+error is recorded every time a selection event instructs us to do something that
+would not be possible with what we believe to be the current selection. Such an
+event would mean that our tracker went wrong previously.
+
+Players that consistently use ``shift+ctrl+hotkey`` to add to hotkeys instead of
+resetting hotkeys with ``ctrl+hotkey`` create tons of issues for this tracker
+because selection changes in hotkeys are not recorded in the replay file.

docs/source/plugins.rst

@@ -0,0 +1,37 @@
+.. currentmodule:: sc2reader.resources
+
+Main Structures
+======================
+
+The outline of the key structures in the replay object.
+
+
+Replay
+--------------
+
+.. autoclass:: Replay
+    :members:
+
+Map
+------------
+
+.. autoclass:: Map
+    :members:
+
+Game Summary
+---------------
+
+.. autoclass:: GameSummary
+    :members:
+
+MapInfo
+---------------
+
+.. autoclass:: MapInfo
+    :members:
+
+MapHeader
+---------------
+
+.. autoclass:: MapHeader
+    :members:

docs/source/primaryresources.rst

@@ -1,9 +1,9 @@
-.. currentmodule:: sc2reader
+.. currentmodule:: sc2reader.factories
 
 SC2Reader
 ======================
 
 The replay factory
 
-.. autoclass:: SC2Reader
-    :members: load_replay, load_replays, register_listener, configure, register_datapack, register_reader, reset
+.. autoclass:: SC2Factory
+    :members:

docs/source/sc2reader.rst

@@ -0,0 +1,47 @@
+.. currentmodule:: sc2reader.objects
+
+Support Structures
+=========================
+
+These dumb data structures help to give meaningful organization and structure to the information in their respective parent resources.
+
+
+Team
+----------------
+
+.. autoclass:: Team
+
+
+Person
+-------------
+
+.. autoclass:: Person
+    :members:
+
+
+Observer
+---------------
+
+.. autoclass:: Observer
+    :members:
+
+
+Player
+------------------
+
+.. autoclass:: Player
+    :members:
+
+
+PlayerSummary
+-----------------
+
+.. autoclass:: PlayerSummary
+    :members:
+
+Graph
+-----------
+
+.. autoclass:: Graph
+    :members:
+

docs/source/supportobjects.rst

@@ -82,7 +82,7 @@ The replay object itself is a dumb data structure; there are no access methods o
     >>> replay.teams
     [<sc2reader.objects.Team object at 0x2b5e410>, <sc2reader.objects.Team object at 0x2b5e4d0>]
 
-Many of the replay attributes are nested data structures which are generally all pretty dumb as well. The idea being that you should be able to access almost anything with a mixture of indexes and dot notation. Clean and simple accessibility is one of the primary design goals for sc2reader. 
+Many of the replay attributes are nested data structures which are generally all pretty dumb as well. The idea being that you should be able to access almost anything with a mixture of indexes and dot notation. Clean and simple accessibility is one of the primary design goals for sc2reader.
 
 ::
 
@@ -125,7 +125,7 @@ Similar formatting written in a more verbose and less pythonic way:
         return output
 
 Next we need to format the teams for display. The :class:`Team` and :class:`Player` data structures are pretty straightforward as well so we can apply a bit of string formatting and produce this:
-    
+
 ::
 
     def formatTeams(replay):
@@ -230,4 +230,19 @@ Recognizing that most users will only ever need one active configuration at a ti
         followlinks=True
     )
 
-An ideal prettyPrinter script would let the user configure these options as arguments using the argparse library. Such an expansion is beyond the scope of sc2reader though, so we'll leave it as an exercise to the reader.
+Many of your replay files might be custom games for which events cannot be parsed. Since the pretty printer doesn't use game event information in its output we can limit the parse level of the replay to stop after loading the basic details. This will make the pretty printer work for custom games as well.
+
+::
+
+    import sc2reader
+
+    sc2reader.load_replay(path, load_level=1)
+
+There are 4 available load levels:
+
+* 0: Parses the replay header for version, build, and length information
+* 1: Also parses the replay.details file for player, team, winner, map, and time information
+* 2: Also parses the replay.message.events file for chat messages and player pings.
+* 3: Also parses the replay.events file for game event information.
+
+So that's it! An ideal prettyPrinter script might let the user configure these options as arguments using the argparse library. Such an expansion is beyond the scope of sc2reader though, so we'll leave it that one to you.