Docs Tutorials (#1)

* Hanoi Tutorial

Signed-off-by: jparisu <[email protected]>

* NQueens Tutorial

Signed-off-by: jparisu <[email protected]>

* Mastermind and Coints tutorial

Signed-off-by: jparisu <[email protected]>

* Add fixes to games

Signed-off-by: jparisu <[email protected]>

* Add Slicing Puzzle

Signed-off-by: jparisu <[email protected]>

* Add a lot of things

Signed-off-by: jparisu <[email protected]>

* Add installation instruction

Signed-off-by: jparisu <[email protected]>

---------

Signed-off-by: jparisu <[email protected]>

.gitignore

@@ -158,3 +158,7 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+
+# .test for manual testing
+.test/

README.md

@@ -48,3 +48,11 @@ There are some resources under `resources` folder with util information and impl
 
 - `play_hanoi.ipynb`: Jupyter notebook to play Towers of Hanoi. It installs and plays all along.
 - `create_player_coins.ipynb`: Jupyter notebook with everything set up to create a player and play against a random player `Coins` game.
+
+---
+
+## Installation
+
+### From source
+
+```bash

docs/conf.py

@@ -3,3 +3,12 @@
 
 extensions = ['sphinx.ext.autodoc']
 html_theme = 'sphinx_rtd_theme'
+
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'

docs/index.rst

@@ -1,23 +1,31 @@
 
+.. include:: src/titlepage.rst
+
 .. toctree::
-   :caption: Introduction
+   :caption: Project
    :maxdepth: 2
    :hidden:
 
-   /src/titlepage
+   /src/getting_started
 
 
 .. toctree::
-   :caption: Project
+   :caption: Players
    :maxdepth: 2
    :hidden:
 
-   /src/project
+   /src/players/players
+   /src/players/random
 
 
 .. toctree::
    :caption: Games
    :maxdepth: 2
    :hidden:
 
-   /src/games
+   /src/games/games
+   /src/games/tutorials/hanoi
+   /src/games/tutorials/slicing
+   /src/games/tutorials/nqueens
+   /src/games/tutorials/coins
+   /src/games/tutorials/mastermind

docs/src/games/games.rst

@@ -0,0 +1,193 @@
+.. _games:
+
+#####
+Games
+#####
+
+In this module there is explained the structure of a **Game** or **Rule**.
+It also enumerates the different games supported so far by the library.
+
+==========
+Interfaces
+==========
+
+There are 3 main interfaces that represent a **game**.
+The *IGameRules* holds the logic of the game.
+The *IPosition* represents a position or state of the game regarding a specific set of rules.
+The *IMovement* represents a movement of the game that goes from one position to another.
+
+.. _rules:
+
+------
+IRules
+------
+
+Represent the rules of a game implementing the following methods:
+
+.. list-table::
+
+  * - **Method**
+    - **Description**
+    - **Arguments type**
+    - **Return type**
+    - **Must be implemented for each game**
+
+  * - ``n_players()``.
+    - The number of players
+    - ``-``
+    - ``int``
+    - *Yes*.
+
+  * - ``first_position()``.
+    - The initial position.
+    - ``-``
+    - ``IPosition``
+    - *Yes*.
+
+  * - ``next_position()``.
+    - The next position giving a position and a move.
+    - ``movement: IMovement, position: IPosition``
+    - ``IPosition``
+    - *Yes*.
+
+  * - ``possible_movements()``.
+    - The possible moves giving a position.
+    - ``IPosition``
+    - ``List[IMovements]``
+    - *Yes*.
+
+  * - ``finished()``.
+    - Whether a position is terminal.
+    - ``IPosition``
+    - ``bool``
+    - *Yes*.
+
+  * - ``score()``.
+    - The score of a terminal position.
+    - ``IPosition``
+    - ``ScoreBoard``
+    - *Yes*.
+
+  * - ``is_movement_possible()``.
+    - Whether a move is possible giving a position.
+    - ``movement: IMovement, position: IPosition``
+    - ``bool``
+    - *No*.
+
+
+
+.. _movement:
+
+---------
+IMovement
+---------
+
+Represent a movement of a game.
+It does not have general methods, as each movement depends on the rules of the specific game.
+
+
+.. _position:
+
+---------
+IPosition
+---------
+
+Represent a position of a game.
+This means, a state, a position of a board, a position in a map, etc.
+Some variables referring to the position may be stored in the rules object that has generated this position.
+
+.. list-table::
+
+  * - **Method**
+    - **Description**
+    - **Arguments type**
+    - **Return type**
+    - **Must be implemented for each game**
+
+  * - ``next_player()``.
+    - The next player to play.
+    - ``-``
+    - ``PlayerIndex``
+    - *Yes*.
+
+  * - ``get_rules()``.
+    - Rules that has generated this position.
+    - ``-``
+    - ``IGameRules``
+    - *No*.
+
+==========
+ScoreBoard
+==========
+
+The Score measured in a ``float`` variable indicates for each player how good the final game went.
+After finishing any game, you get a ``ScoreBoard`` that holds the score for each player.
+
+.. note::
+
+    Always remember that the lowest score is the best one.
+
+
+.. _games_available:
+
+===============
+Games available
+===============
+
+This is a list of all the games supported and its characteristics:
+
+.. list-table:: Games
+
+   * - **Game name**
+     - **Folder**
+     - **Tutorial**
+     - **Short description**
+     - **Number of players**
+     - **Deterministic / Random**
+     - **Perfect information / Hidden information**
+     - **Details**
+
+   * - **Hanoi**
+     - ``IArena.games.Hanoi``
+     - :ref:`hanoi_tutorial`
+     - The classic Hanoi's Tower game.
+     - 1
+     - Deterministic
+     - Perfect information
+     -
+
+   * - **SlicingPuzzle**
+     - ``IArena.games.SlicingPuzzle``
+     - :ref:`slicing_tutorial`
+     - The classic Slicing Puzzle game.
+     - 1
+     - Deterministic
+     - Perfect information
+     -
+
+   * - **NQueens**
+     - ``IArena.games.NQueens``
+     - :ref:`nqueens_tutorial`
+     - The classic N-Queens game.
+     - 1
+     - Deterministic
+     - Perfect information
+     - *Min score*: 0
+
+   * - **Coins**
+     - ``IArena.games.Coins``
+     - :ref:`coins_tutorial`
+     - Roman's coin game.
+     - 2
+     - Deterministic
+     - Perfect information
+     - **0 sum game**
+
+   * - **Mastermind**
+     - ``IArena.games.Mastermind``
+     - :ref:`mastermind_tutorial`
+     - The classic Mastermind game.
+     - 1
+     - Deterministic
+     - Hidden information
+     -

docs/src/games/tutorials/coins.rst

@@ -0,0 +1,115 @@
+.. _coins_tutorial:
+
+#####
+Coins
+#####
+
+.. figure:: /resources/images/coins.svg
+
+This game is a classical 2 players game called *Roman Coins*.
+By turns, each player takes between ``A`` and ``B`` coins from a pile of ``N`` coins.
+The player that can no longer take a coins loses.
+
+This is a **0 sum** game with perfect information.
+
+====
+Goal
+====
+
+The goal of this game is to be the last player to take a coin.
+
+-----
+Score
+-----
+
+- The player that takes the last coin:
+  - ``0``
+- The player that cannot take a coin:
+  - ``1``
+
+======
+Import
+======
+
+.. code-block:: python
+
+  import IArena.games.Coins.CoinsPosition as CoinsPosition
+  import IArena.games.Coins.CoinsMovement as CoinsMovement
+  import IArena.games.Coins.CoinsRules as CoinsRules
+
+
+========
+Movement
+========
+
+A movement is represented by an ``int`` representing the number of coins to take:
+
+- ``n``
+  - ``int``
+  - ``A <= tower_source < min(B, number of coins remaining)``
+  - Number of coins to remove
+
+
+.. code-block:: python
+
+    movement = CoinsMovement(n=2) # Remove 2 coins from the stack
+
+
+========
+Position
+========
+
+A position is represented by an ``int`` describing the size of the remaining stack.
+
+.. code-block:: python
+
+  # position : CoinsPosition
+  len(position)      # Size of the stack
+  position.n         # Same as len
+
+
+=====
+Rules
+=====
+
+This games has every methods of :ref:`IRules <infrastructure_rules>`.
+
+It counts with 2 methods to get the minimum and maximum number of coins that can be taken:
+
+- ``rules.min_play() -> int``
+- ``rules.max_play() -> int``
+
+
+-----------
+Constructor
+-----------
+
+Can receive 3 arguments:
+
+- ``initial_position``
+  - ``int``
+  - ``0 <= initial_position``
+  - Initial size of the stack
+  - Default: ``15``
+- ``min_play``
+  - ``int``
+  - ``1 <= min_play``
+  - Minimum number of coins that can be taken in a turn
+  - Default: ``1``
+- ``max_play``
+  - ``int``
+  - ``min_play <= max_play``
+  - Maximum number of coins that can be taken in a turn
+  - Default: ``3``
+
+
+.. code-block:: python
+
+  # Stack of 15 coins with min_play=1 and max_play=3
+  rules = coinsRules()
+
+  # Stack of 20 coins with min_play=2 and max_play=5
+  rules = coinsRules(
+    initial_position=20,
+    min_play=2,
+    max_play=5)