Add quickstart

docs/index.rst

@@ -7,6 +7,7 @@ This is a Python module for implementing bots for Starcraft II.
    :maxdepth: 2
    :caption: Contents:
 
+   quickstart
    unit
    managers
    playerconstants

docs/quickstart.rst

+.. TODO: How should we host the binaries
+
+Creating your first bot
+=======================
+
+The goal of this page is to get you quickly started using the API. The 
+following code block is the bare minimum you need to start Starcraft II and run 
+your own bot.
+
+.. code-block:: python
+
+   from library import *
+
+   class DoNothingBot(IDABot):
+       def __init__(self):
+           IDABot.__init__(self)
+   
+       def on_game_start(self):
+           IDABot.on_game_start(self)
+   
+       def on_step(self):
+           IDABot.on_step(self)
+   
+   
+   def main():
+       coordinator = Coordinator()
+       bot1 = DoNothingBot()
+   
+       participant_1 = create_participants(Race.Terran, bot1)
+       participant_2 = create_computer(Race.Random, Difficulty.Easy)
+   
+       coordinator.set_participants([participant_1, participant_2])
+   
+       coordinator.launch_starcraft()
+       coordinator.start_game("InterloperTest.SC2Map")
+   
+       while coordinator.update():
+           pass
+   
+   
+   if __name__ == "__main__":
+       main()
+
+Now, let us break it down piece by piece to understand it.
+
+.. code-block:: python
+
+   from library import *
+
+.. TODO: Should we really encourage this behaviour?
+This imports everything from the library into your namespace. 
+
+Next, we need to define our bot.
+
+.. code-block:: python
+
+   class DoNothingBot(IDABot):
+       def __init__(self):
+           IDABot.__init__(self)
+   
+       def on_game_start(self):
+           IDABot.on_game_start(self)
+   
+       def on_step(self):
+           IDABot.on_step(self)
+
+A bot which plays Starcraft is defined as a subclass to the class :class:`library.IDABot` which
+contains some help code in order to make implementing your bit more straightforward.
+
+If we look closer at our newly created bot, it has three methods which are all 
+run at different times. The method ``__init__`` is the constructor, which is 
+called whenever the bot is first created.
+
+The method ``on_game_start`` method is run when the game starts. Lastly, the 
+method ``on_step`` is run on every time step of the game and thus where most of 
+the decision making is going to be implemented.
+
+Moving on, we have the code which sets up a game of Starcraft II:
+
+.. code-block:: python
+
+   def main():
+       coordinator = Coordinator()
+       bot1 = DoNothingBot()
+   
+       participant_1 = create_participants(Race.Terran, bot1)
+       participant_2 = create_computer(Race.Random, Difficulty.Easy)
+   
+       coordinator.set_participants([participant_1, participant_2])
+   
+       coordinator.launch_starcraft()
+       coordinator.start_game("InterloperTest.SC2Map")
+   
+       while coordinator.update():
+           pass
+   
+   
+   if __name__ == "__main__":
+       main()
+
+This is where the constructor of the bot is called. If we want to play to bots 
+against each other we could change the row:
+
+.. code-block:: python
+
+   participant_2 = create_computer(Race.Random, Difficulty.Easy)
+
+to:
+
+.. code-block:: python
+
+   bot2 = SomeOtherBot()
+   participant_2 = create_participant(Race.Terran, bot2)
+
+where ``SomeOtherBot`` is a bot defined in the same way as ``DoNothingBot``.