Merge pull request #372 from Axelrod-Python/299

299 - Docs

Author: meatballs

.gitignore

@@ -5,3 +5,4 @@ _build/
 *.log
 dist/
 MANIFEST
+Axelrod.egg-info

.travis.yml

@@ -20,5 +20,7 @@ script:
   - cd ..
   - coverage run --source=axelrod -m unittest discover
   - coverage report -m
+  # Run the doctests
+  - sh doctest
 after_success:
   - coveralls

docs/auto_generate_strategies_list.py

@@ -3,25 +3,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to the documentation for an implementation of Axelrod's tournament in Python
-====================================================================================
-
-This project is both:
-
-* A python library that reproduces Axelrod's tournament.
-* A github experiment allowing anyone to contribute a strategy.
-
-
-Contents:
+Welcome to the documentation for the Axelrod Python library
+===========================================================
 
 .. toctree::
    :maxdepth: 2
 
-   background
-   usage
-   overview_of_strategies
-   index_of_strategies
-   contributing
+   tutorials/index.rst
+   reference/index.rst
 
 
 Indices and tables

docs/background.rst renamed to docs/background/background.rst

@@ -0,0 +1,68 @@
+Glossary
+========
+
+There are a variety of terms used in the documentation and throughout the
+library. Here is an overview:
+
+An action
+---------
+
+An **action** is either :code:`C` or :code:`D`.
+You can access these actions as follows but should not really have a reason to::
+
+    >>> import axelrod as axl
+    >>> axl.Actions.C
+    'C'
+    >>> axl.Actions.D
+    'D'
+
+A play
+------
+
+A **play** is a single player choosing an **action**.
+In terms of code this is equivalent to::
+
+    >>> p1, p2 = axl.Cooperator(), axl.Defector()
+    >>> p1.play(p2)  # This constitues two 'plays' (p1 plays and p2 plays).
+
+This is equivalent to :code:`p2.play(p1)`. Either function invokes both
+:code:`p1.strategy(p2)` and :code:`p2.strategy(p1)`.
+
+A turn
+------
+
+A **turn** is a 1 shot interaction between two players. It is in effect a
+composition of two **plays**.
+
+Each turn has four possible outcomes of a play: :code:`(C, C)`, :code:`(C, D)`,
+:code:`(D, C)`, or :code:`(D, D)`.
+
+A match
+-------
+
+A **match** is a consecutive number of **turns**. The default number of turns
+used in the tournament is 200. Here is a single match between two players over
+10 turns::
+
+    >>> p1, p2 = axl.Cooperator(), axl.Defector()
+    >>> for turn in range(10):
+    ...     p1.play(p2)
+    >>> p1.history, p2.history
+    (['C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C'], ['D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D', 'D'])
+
+A win
+-----
+
+A **win** is attributed to the player who has the higher total score at the end
+of a match. For the example above, :code:`Defector` would win that match.
+
+A round robin
+-------------
+
+A **round robin** is the set of all potential (order invariant) matches between
+a given collection of players.
+
+A tournament
+------------
+
+A **tournament** is a repetition of round robins so as to smooth out stochastic effects.

docs/description.rst

@@ -0,0 +1,12 @@
+Reference
+=========
+
+This section is the reference guide for the various components of the library.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview_of_strategies.rst
+   glossary.rst