Merge pull request #539 from Axelrod-Python/536

Docs reorganisation

axelrod/moran.py

@@ -115,6 +115,7 @@ def play(self):
                 self.__next__()
             except StopIteration:
                 break
+        return self.populations
 
     def __len__(self):
         return len(self.populations)

axelrod/tests/unit/test_moran.py

@@ -39,26 +39,32 @@ def test_two_players(self):
         p1, p2 = axelrod.Cooperator(), axelrod.Defector()
         random.seed(5)
         mp = MoranProcess((p1, p2))
-        mp.play()
+        populations = mp.play()
         self.assertEqual(len(mp), 5)
+        self.assertEqual(len(populations), 5)
+        self.assertEqual(populations, mp.populations)
         self.assertEqual(mp.winning_strategy_name, str(p2))
 
     def test_three_players(self):
         players = [axelrod.Cooperator(), axelrod.Cooperator(),
                    axelrod.Defector()]
         random.seed(5)
         mp = MoranProcess(players)
-        mp.play()
+        populations = mp.play()
         self.assertEqual(len(mp), 7)
+        self.assertEqual(len(populations), 7)
+        self.assertEqual(populations, mp.populations)
         self.assertEqual(mp.winning_strategy_name, str(axelrod.Defector()))
 
     def test_four_players(self):
         players = [axelrod.Cooperator() for _ in range(3)]
         players.append(axelrod.Defector())
         random.seed(10)
         mp = MoranProcess(players)
-        mp.play()
+        populations = mp.play()
         self.assertEqual(len(mp), 9)
+        self.assertEqual(len(populations), 9)
+        self.assertEqual(populations, mp.populations)
         self.assertEqual(mp.winning_strategy_name, str(axelrod.Defector()))
 
     @given(strategies=lists(sampled_from(axelrod.strategies),
@@ -76,7 +82,8 @@ def test_property_players(self, strategies, rm):
         """Hypothesis test that randomly checks players"""
         players = [s() for s in strategies]
         mp = MoranProcess(players)
-        mp.play()
+        populations = mp.play()
+        self.assertEqual(populations, mp.populations)
         self.assertIn(mp.winning_strategy_name, [str(p) for p in players])
 
     def test_reset(self):

docs/index.rst

@@ -6,6 +6,51 @@
 Welcome to the documentation for the Axelrod Python library
 ===========================================================
 
+Here is quick overview of what can be done with the library.
+
+
+Quick start
+-----------
+
+Create matches between two players::
+
+    >>> import axelrod as axl
+    >>> players = (axl.Alternator(), axl.TitForTat())
+    >>> match = axl.Match(players, 5)
+    >>> interactions = match.play()
+    >>> interactions
+    [('C', 'C'), ('D', 'C'), ('C', 'D'), ('D', 'C'), ('C', 'D')]
+
+Build full tournaments between groups of players::
+
+    >>> import axelrod as axl
+    >>> players = (axl.Cooperator(), axl.Alternator(), axl.TitForTat())
+    >>> tournament = axl.Tournament(players)
+    >>> results = tournament.play()
+    >>> results.ranked_names
+    ['Alternator', 'Tit For Tat', 'Cooperator']
+
+Study the evolutionary process using a Moran process::
+
+    >>> import axelrod as axl
+    >>> players = (axl.Cooperator(), axl.Alternator(), axl.TitForTat())
+    >>> mp = axl.MoranProcess(players)
+    >>> populations = mp.play()
+    >>> populations  # doctest: +SKIP
+    [Counter({'Alternator': 1, 'Cooperator': 1, 'Tit For Tat': 1}),
+     Counter({'Alternator': 1, 'Cooperator': 1, 'Tit For Tat': 1}),
+     Counter({'Cooperator': 1, 'Tit For Tat': 2}),
+     Counter({'Cooperator': 1, 'Tit For Tat': 2}),
+     Counter({'Tit For Tat': 3})]
+
+As well as this, the library has a growing collection of strategies. The
+:ref:`strategies-index` gives a description of them.
+
+For further details there is a library of tutorials available:
+
+Tutorials
+---------
+
 .. toctree::
    :maxdepth: 3
 

docs/reference/all_strategies.rst

@@ -1,5 +1,7 @@
-Strategies
-==========
+.. _strategies-index:
+
+Strategies index
+================
 
 Here are the docstrings of all the strategies in the library.
 

docs/tutorials/advanced/index.rst

@@ -1,13 +1,14 @@
-Advanced
-========
+Further capabilities in the library
+===================================
 
-This is a section aiming to showcase some problems solved and/or insights gained
-using the Axelrod library. Please be the first to submit such a tutorial!
+This section shows some of the more intricate capabilities of the library.
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   classification_of_strategies.rst
    strategy_transformers.rst
    making_tournaments.rst
+   reading_and_writing_interactions.rst

docs/tutorials/advanced/making_tournaments.rst

@@ -36,7 +36,6 @@ To do this let us create a new class to generate matches::
     ...                     match = self.build_single_match(pair, noise)
     ...                     yield (player1_index, player2_index), match
 
-
 Using this class we can create a tournament with little effort::
 
     >>> players = [axl.Cooperator(), axl.Defector(), axl.TitForTat(),
@@ -75,3 +74,24 @@ before::
 
     >>> results.ranked_names  # doctest: +SKIP
     ['Defector', 'Alternator', 'Grudger', 'Tit For Tat', 'Cooperator']
+
+Note: the :code:`axelrod.MatchGenerator` also has a :code:`build_single_match`
+method which can be overwritten (similarly to above) if the type of a particular
+match should be changed.
+
+For example the following could be used to create a tournament that randomly
+builds matches that were either 200 turns or single 1 shot games::
+
+    >>> import axelrod as axl
+    >>> import random
+    >>> class OneShotOrRepetitionMatchups(axl.RoundRobinMatches):
+    ...     """Inherit from the `axelrod.match_generator.RoundRobinMatches` class"""
+    ...
+    ...
+    ...     def build_single_match(self, pair, noise=0):
+    ...         """Create a single match for a given pair"""
+    ...         if random.random() < 0.5:
+    ...             return Match(
+    ...                 pair, 200, self.game, self.deterministic_cache, noise)
+    ...         return Match(
+    ...             pair, 1, self.game, self.deterministic_cache, noise)