Improve the documentation and bump the version.

Author: GraylinKim

README.rst

@@ -12,7 +12,7 @@ under the open MIT license. Currently powering:
 
 * Websites: `ggtracker.com`_, `gamereplays.org`_
 * Tools: `The Core`_
-* Research: `Build Order Classification`
+* Experiments: `Midi Conversion`_
 
 Our secondary goal is to become a reference implementation for people looking
 to implement parsers in other languages. The following is a list of partial
@@ -42,6 +42,8 @@ the three primary resource types listed below. For a more detailed and exact
 description of the information that can be extracted please consult the
 `documentation`_ hosted on Read the Docs.
 
+The library is production ready and reasonably stable.
+
 
 Replays
 -------------
@@ -51,25 +53,35 @@ Replays can be parsed for the following general types of information:
 - Replay details (map, length, version, expansion, datetime, game type/speed, ...)
 - Player details (name, race, team, color, bnet url, win/loss, ...)
 - Message details (text, time, player, target, pings, ...)
-
-Additional information can be parsed from ladder replays and replays from basic
-unmodded private "custom" games. This information includes:
-
 - Unit Selection and Hotkey (Control Group) events.
 - Resource Transfers and Requests (but not collection rate or unspent totals!)
 - Unfiltered Unit commands (attack, move, train, build, psi storm, etc)
 - Camera Movements for all players and observers.
 
-In general, all player actions are recorded but game state information is not.
-In some cases, further game state information can be extracted from this raw
-information:
+Replays from release 2.0.8 on ward make additional state information available:
+
+- Unit states - creation time, positions, and deaths times
+- Player resource stats - collection rates/unspent totals
+- Player spending stats - resources spent and lost
+
+Further game state information can be extracted from this raw information:
 
 - All unit selections and hotkey values for every frame of the game.
 - APM/EPM and its untold variations.
+- Supply counts, expansion timings, build orders, etc
+
+We have data dictionaries in place for standard games that make unit meta data
+available.  Unit meta data is currently limited to:
 
-We are in the process of building data dictionaries for all the SC2 units and
-abilities which should enable much more creative and robust analysis of the
-raw event stream found in replay files.
+- Costs - mineral, vespene, supply
+- Classification - army, building, worker
+
+Additionally, abilities that create units/buildings have the built unit linked
+with the build time in game seconds.
+
+Unfortunately this information IS NOT currently versioned and is only accurate
+for the latest builds of Starcraft. Versioned meta data support will be added
+in future releases.
 
 
 Maps
@@ -87,7 +99,12 @@ There's a lot more in here to be had for the adventurous.
 Game Summaries
 -----------------
 
-Tons of data parsed. Thank you Prillan and others from `Team Liquid`_.
+Game Summary files are downloaded by the client in order to allow you to view
+the game summary from your match history. Prior to 2.0.8 they were the only
+way to get the information from the summary screen. Since the 2.0.8 release
+you have been able to compute this information yourself from the replay files.
+
+Thank you Prillan and `Team Liquid`_ for helping to decode this file.
 
 * Lobby Properties (game speed, game type, ...)
 * Player Information (Race, Team, Result, bnet info, ...)
@@ -98,6 +115,9 @@ Tons of data parsed. Thank you Prillan and others from `Team Liquid`_.
 Parsing on these files is now production ready for those that can get them. See
 the `Team Liquid`_ thread for details on how to go about getting them.
 
+Again, these files are generally unnecessary after the 2.0.8 release.
+
+
 
 Example Usage
 =====================
@@ -136,7 +156,7 @@ Organizing your 1v1 replays by race played and matchup and sortable by length::
     sorted_base = 'sorted'
     path_to_replays = 'my/replays'
 
-    for replay in sc2reader.load_replays(sys.argv[1], load_level=1):
+    for replay in sc2reader.load_replays(sys.argv[1], load_level=2):
         if replay.real_type != '1v1':
             continue
 
@@ -235,8 +255,9 @@ To run the tests just use::
 When repeatedly running tests it can be very helpful to make sure you've
 set a local cache directory to prevent long fetch times from battle.net::
 
-    mkdir local_cache
     export SC2READER_CACHE_DIR=local_cache
+    # or
+    SC2READER_CACHE_DIR=local_cache py.test
 
 Good luck, have fun!
 
@@ -265,19 +286,21 @@ Acknowledgements
 =======================
 
 Thanks to all the awesome developers in the SC2 community that helped out
-and kept this project going. Special thanks to the people of the awesome
-`phpsc2replay`_ project whose public documentation and source code made
-starting this library possible and to sc2replay-csharp for setting us
-straight on game events parsing and assisting with our v1.5 upgrade.
-I'd also like to thank ggtracker sponsoring further development and for
-providing the thousands of test files used while adding s2gs and HotS Beta
-support.
+and kept this project going.
 
+* Special thanks to the people of the awesome (but abandoned!) `phpsc2replay`_
+  project whose public documentation and source code made starting this library
+  possible.
+* Thanks to `sc2replay-csharp`_ for setting us straight on game events parsing
+  and assisting with our v1.5 upgrade.
+* Thanks to `ggtracker.com`_ for sponsoring further development and providing
+  the thousands of test files used while adding s2gs and HotS support.
+* Thanks to Blizzard for allowing and supporting development of 3rd party tools.
 
 
-.. _Build Order Classification: https://github.com/grahamjenson/sc2reader
 .. _ggtracker.com: http://ggtracker.com
 .. _gamereplays.org: http://www.gamereplays.org/starcraft2/
+.. _Midi Conversion: https://github.com/obohrer/sc2midi
 .. _sc2reader.scripts: https://github.com/GraylinKim/sc2reader/tree/master/sc2reader/scripts
 .. _The Core: http://www.teamliquid.net/forum/viewmessage.php?topic_id=341878
 .. _PyPy: http://pypy.org/

docs/source/conf.py

@@ -41,16 +41,16 @@
 
 # General information about the project.
 project = u'sc2reader'
-copyright = u'2011'
+copyright = u'2011-2013'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.4.0'
+version = '0.5.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+release = '0.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -179,7 +179,7 @@
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'sc2reader.tex', u'sc2reader Documentation',
-   u'Graylin Kim, Bas Peschier', 'manual'),
+   u'Graylin Kim', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

docs/source/dataobjects.rst

@@ -0,0 +1,28 @@
+.. currentmodule:: sc2reader.data
+
+Data Objects
+=====================
+
+Objects representing in-game objects.
+
+
+Unit
+--------------------------
+
+.. autoclass:: Unit
+	:members:
+
+
+Ability
+--------------------------
+
+.. autoclass:: Ability
+	:members:
+
+
+
+Build
+--------------------------
+
+.. autoclass:: Build
+	:members:

docs/source/decoders.rst

@@ -0,0 +1,18 @@
+.. currentmodule:: sc2reader.decoders
+
+Decoders
+===============
+
+Used to decode the low level contents of files extracted from MPQFiles
+
+ByteDecoder
+--------------------------
+
+.. autoclass:: ByteDecoder
+	:members:
+
+BitPackedDecoder
+--------------------------
+
+.. autoclass:: BitPackedDecoder
+	:members:

docs/source/events/game.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: sc2reader.events.game
+
+Game Events
+=============
+
+Coming soon!
+
+.. automodule:: sc2reader.events.game
+	:members:

docs/source/events/index.rst

@@ -0,0 +1,16 @@
+Events
+============
+
+All of the gamplay and state information contained in the replay is packed into events.
+
+* :doc:`game`: Human actions and certain triggered events
+* :doc:`message`: Message and Pings to other players.
+* :doc:`tracker`: Game state information
+
+.. toctree::
+	:hidden:
+
+	game
+	message
+	tracker
+

docs/source/events/message.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: sc2reader.events.message
+
+Message Events
+===================
+
+Coming soon!
+
+.. automodule:: sc2reader.events.message
+	:members:

docs/source/events/tracker.rst

@@ -0,0 +1,7 @@
+.. currentmodule:: sc2reader.events
+
+Tracker Events
+=====================
+
+.. automodule:: sc2reader.events.tracker
+	:members:

docs/source/factories.rst

@@ -0,0 +1,32 @@
+.. currentmodule:: sc2reader.factories
+
+Factories
+==============
+
+Factories are used to load SCII resources from file-like objects and paths to file-like objects. Objects must implement ``read()`` such that it retrieves all the file contents.
+
+
+SC2Factory
+--------------------------
+
+.. autoclass:: SC2Factory
+	:members:
+
+
+DictCachedSC2Factory
+--------------------------
+
+.. autoclass:: DictCachedSC2Factory
+	:members:
+
+FileCachedSC2Factory
+--------------------------
+
+.. autoclass:: FileCachedSC2Factory
+	:members:
+
+DoubleCachedSC2Factory
+--------------------------
+
+.. autoclass:: DoubleCachedSC2Factory
+	:members:

docs/source/index.rst

@@ -35,16 +35,21 @@ The best way to learn how to pick sc2Reader up and get started is probably by ex
 Reference Pages
 -----------------------
 
-SC2 replays hold a ton of information. The following reference pages were put together to help you quickly find the information you need.
+The following reference pages were put together to help you quickly find the information you need.
 
 .. toctree::
 
     faq
     sc2reader
-    primaryresources
+    mainobjects
     supportobjects
-    utilityclasses
+    dataobjects
     plugins
+    factories
+    decoders
+    utilities
+    events/index
+
 
 
 .. toctree::
@@ -54,8 +59,12 @@ SC2 replays hold a ton of information. The following reference pages were put to
 
     faq
     sc2reader
-    primaryresources
+    mainobjects
     supportobjects
-    utilityclasses
+    dataobjects
     plugins
+    factories
+    decoders
+    utilities
     tutorials/*
+    events/index