diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index 4a6280c..712f45f 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -22,13 +22,17 @@ jobs: with: python-version: '3.x' - # - name: Install dependencies - # run: | - # python -m pip install --upgrade pip - # pip install -r requirements.txt + - name: Extract branch name + id: branch + run: echo "BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_ENV + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt - name: Install package from current branch - run: pip install --upgrade git+https://github.com/jparisu/sIArena.git@${GITHUB_REF#refs/heads/} + run: pip install --upgrade git+https://github.com/jparisu/IArena.git@${BRANCH} - name: Run tests run: pytest diff --git a/README.md b/README.md index 6d30952..5004c10 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ There are some games implemented under `src/IArena/games`: - `FieldWalk`: Similar to `BlindWalk` but with access to the whole map from the beginning. - `Coins`: 2 player Roman coins game. - `Nim`: 2 player well known Nim game. +- ... ### Players @@ -38,6 +39,7 @@ There are some players implemented under `src/IArena/players`: - `RandomPlayer`: Play a random movement from the movements possible. - `FirstPlayer`: Play the first movement from the movements possible. - `LastPlayer`: Play the last movement from the movements possible. +- ... ### Arena @@ -46,6 +48,7 @@ Implementations of different ways of playing and measuring scores: - `GenericGame`: Decide the rules and the players and create a basic loop game. - `BroadcastGame`: Similar to `GenericGame` but print out the player actions. - `PlayableGame`: Play a game with all players `PlayablePlayer`. +- ... --- @@ -63,3 +66,5 @@ There are some resources under `resources` folder with util information and impl ### From source ```bash +pip install --upgrade git+https://github.com/jparisu/IArena.git +``` diff --git a/docs/conf.py b/docs/conf.py index a877bcb..56b4001 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,3 +12,10 @@ # The master toctree document. master_doc = 'index' + +# The spelling list filename. +spelling_word_list_filename=['spelling/spelling_wordlist.txt'] + +# Change tab title +release = '1.0.0' +html_title = f"{project} {release} Documentation" diff --git a/docs/index.rst b/docs/index.rst index 0787e1b..d4dcaae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,8 @@ :maxdepth: 2 :hidden: - /src/getting_started - /src/installation + /src/getting_started/getting_started + /src/getting_started/installation .. toctree:: @@ -51,4 +51,4 @@ :maxdepth: 2 :hidden: - /rst/appendixes/glossary + /src/appendixes/glossary diff --git a/docs/spelling/spelling_wordlist.txt b/docs/spelling/spelling_wordlist.txt index b76c4a9..72c2b6d 100644 --- a/docs/spelling/spelling_wordlist.txt +++ b/docs/spelling/spelling_wordlist.txt @@ -1,2 +1,11 @@ Colab IArena +IGameRules +IMovement +IPosition +IPlayer +Tic +Tac +Toe +conda +NQueens diff --git a/docs/src/appendixes/glossary.rst b/docs/src/appendixes/glossary.rst new file mode 100644 index 0000000..f0f722e --- /dev/null +++ b/docs/src/appendixes/glossary.rst @@ -0,0 +1,26 @@ + +.. _glossary: + +######## +Glossary +######## + +.. glossary:: + + Arena + A class that represents the game flow. Uses one GameRule and several players to play a game, returning the final score. + + GameRule + A class that defines the rules of a game. It contains methods to help creating the game flow. + + Movement + A class that represents a movement in a game. Along with GameRules, generates new Positions given a source one. + + Player + A class that represents a player in a game. It contains the method to return a movement given a position. + + Position + A class that represents a specific state of a game. Along with the GameRules, it defines the game. + + Score + A class that represents the score of a terminated game. Each player has its own score. diff --git a/docs/src/games/games.rst b/docs/src/games/games.rst index a5b5f17..9e506bf 100644 --- a/docs/src/games/games.rst +++ b/docs/src/games/games.rst @@ -18,9 +18,9 @@ The *IMovement* represents a movement of the game that goes from one position to .. _rules: ------- -IRules ------- +---------- +IGameRules +---------- Represent the rules of a game implementing the following methods: @@ -236,3 +236,12 @@ This is a list of all the games supported and its characteristics: - Random - Hidden information - + + * - **Connect 4** + - ``IArena.games.Connect4`` + - :ref:`connect4_tutorial` + - Connect 4 game. + - 2 + - Deterministic + - Perfect information + - **0 sum game** diff --git a/docs/src/games/tutorials/coins.rst b/docs/src/games/tutorials/coins.rst index 703f353..2596661 100644 --- a/docs/src/games/tutorials/coins.rst +++ b/docs/src/games/tutorials/coins.rst @@ -73,7 +73,6 @@ A position is represented by an ``int`` describing the size of the remaining sta Rules ===== -This games has every methods of :ref:`IRules `. It counts with 2 methods to get the minimum and maximum number of coins that can be taken: diff --git a/docs/src/games/tutorials/fieldwalk.rst b/docs/src/games/tutorials/fieldwalk.rst index ba3099f..0a048c0 100644 --- a/docs/src/games/tutorials/fieldwalk.rst +++ b/docs/src/games/tutorials/fieldwalk.rst @@ -94,7 +94,6 @@ One indicates the x axis, other the y axis and the last one the cost to arrive t Rules ===== -This games has every methods of :ref:`IRules `. ----------- Constructor diff --git a/docs/src/games/tutorials/hanoi.rst b/docs/src/games/tutorials/hanoi.rst index 2458c71..9ddbd13 100644 --- a/docs/src/games/tutorials/hanoi.rst +++ b/docs/src/games/tutorials/hanoi.rst @@ -83,7 +83,6 @@ The disks go from ``0`` to ``N-1`` in ascending order being ``0`` the highest di Rules ===== -This games has every methods of :ref:`IRules `. ----------- Constructor diff --git a/docs/src/games/tutorials/highestcard.rst b/docs/src/games/tutorials/highestcard.rst index fc761f0..08db4bb 100644 --- a/docs/src/games/tutorials/highestcard.rst +++ b/docs/src/games/tutorials/highestcard.rst @@ -9,7 +9,7 @@ Highest Card This game is a card game with ``N`` players and ``NxM`` cards. The objective of the game is to guess the number of rounds that the player will win with its ``M`` cards. -Each player guesses in secret at the begining knowing only their ``M`` cards, for how many rounds it will win. +Each player guesses in secret at the beginning knowing only their ``M`` cards, for how many rounds it will win. Then, ``M`` rounds are played in which each player plays its highest card. The player that gets closer to the real number of rounds that it wins without passing it, wins the game. @@ -84,7 +84,6 @@ Each player can get its cards from the position, and only its cards. Rules ===== -This games has every methods of :ref:`IRules `. It counts with 2 method to retrieve the values of the game diff --git a/docs/src/games/tutorials/mastermind.rst b/docs/src/games/tutorials/mastermind.rst index a39b664..1da562f 100644 --- a/docs/src/games/tutorials/mastermind.rst +++ b/docs/src/games/tutorials/mastermind.rst @@ -15,7 +15,7 @@ The goal is to guess the code in the fewest number of turns. Some changes have been made to the original game: -- There is only a one player game (guesser) while the other player (codemaker) is the game itself. +- There is only a one player game (guesser) while the other player (password-maker) is the game itself. - Instead of colors we use numbers. - The clues of each guess is not only the number of appearance and correctness, but are linked with a direct position in the guess. - Numbers could be repeated in the secret code. @@ -105,7 +105,6 @@ or whether it is not present in the secret code (``0``). Rules ===== -This games has every methods of :ref:`IRules `. It counts with 2 methods to get the minimum and maximum number of coins that can be taken: diff --git a/docs/src/games/tutorials/nim.rst b/docs/src/games/tutorials/nim.rst index ccc7989..2cb75ce 100644 --- a/docs/src/games/tutorials/nim.rst +++ b/docs/src/games/tutorials/nim.rst @@ -84,7 +84,6 @@ A position is represented by a ``list`` of ``int`` describing each row: Rules ===== -This games has every methods of :ref:`IRules `. ----------- diff --git a/docs/src/games/tutorials/nqueens.rst b/docs/src/games/tutorials/nqueens.rst index 9043689..a3d6433 100644 --- a/docs/src/games/tutorials/nqueens.rst +++ b/docs/src/games/tutorials/nqueens.rst @@ -47,14 +47,14 @@ Movement A movement is represented by a tuple ``new_position`` of 2 ``int``: - ``new_position`` - - ``tuple(int, int)`` - - ``int`` - - ``0 <= tower_source < N`` - - Number of row to place the next queen. - - ``tuple(int, int)`` - - ``int`` - - ``0 <= tower_source < N`` - - Number of column to place the next queen. + - ``tuple(int, int)`` + - ``int`` + - ``0 <= tower_source < N`` + - Number of row to place the next queen. + - ``tuple(int, int)`` + - ``int`` + - ``0 <= tower_source < N`` + - Number of column to place the next queen. .. code-block:: python @@ -82,7 +82,6 @@ Each movement represents the position of a queen in the board. Rules ===== -This games has every methods of :ref:`IRules `. Remember that using ``score`` method can give the current result of the game: diff --git a/docs/src/games/tutorials/prisoner.rst b/docs/src/games/tutorials/prisoner.rst index a0f3345..e9f2d0d 100644 --- a/docs/src/games/tutorials/prisoner.rst +++ b/docs/src/games/tutorials/prisoner.rst @@ -79,7 +79,6 @@ The rules are stored within the rules Rules ===== -This games has every methods of :ref:`IRules `. It counts with 1 method to retrieve the score matrix: @@ -90,7 +89,7 @@ It counts with 1 method to retrieve the score matrix: Constructor ----------- -To construct the rules, it can give the score table, or let it be creater randomly: +To construct the rules, it can give the score table, or let it be created randomly: #. Using a secret code already defined. diff --git a/docs/src/games/tutorials/slicing.rst b/docs/src/games/tutorials/slicing.rst index ead1444..f575d67 100644 --- a/docs/src/games/tutorials/slicing.rst +++ b/docs/src/games/tutorials/slicing.rst @@ -109,7 +109,6 @@ It counts with the following methods: Rules ===== -This games has every methods of :ref:`IRules `. ----------- diff --git a/docs/src/games/tutorials/tictactoe.rst b/docs/src/games/tutorials/tictactoe.rst index df5ec32..727a3af 100644 --- a/docs/src/games/tutorials/tictactoe.rst +++ b/docs/src/games/tutorials/tictactoe.rst @@ -90,7 +90,6 @@ Each position is represented by an integer, ``0`` for empty, ``1`` for player 1 Rules ===== -This games has every methods of :ref:`IRules `. ----------- diff --git a/docs/src/getting_started.rst b/docs/src/getting_started/getting_started.rst similarity index 84% rename from docs/src/getting_started.rst rename to docs/src/getting_started/getting_started.rst index b874a36..c1a7ab5 100644 --- a/docs/src/getting_started.rst +++ b/docs/src/getting_started/getting_started.rst @@ -8,8 +8,9 @@ Getting Started Project Overview ================ -In order to know more about the infrastructure and design of this software from a developer point of view, -check the :ref:`infrastructure` section. +.. warning:: + + Coming soon. ============ @@ -45,10 +46,6 @@ In order to do so follow this instructions with the game desired: game = PlayableGame(rules) score = game.play() -.. note:: - - Always remember that the lowest score is the best one. - ============== Build a player diff --git a/docs/src/installation.rst b/docs/src/getting_started/installation.rst similarity index 77% rename from docs/src/installation.rst rename to docs/src/getting_started/installation.rst index 83e924d..1eef5c5 100644 --- a/docs/src/installation.rst +++ b/docs/src/getting_started/installation.rst @@ -10,7 +10,7 @@ Installation Google Colab ============ -Using :ref:`Google Colab ` is the easiest way to get started. +Using `Google Colab ` is the easiest way to get started. Just add in the first cell of your notebook: .. code-block:: python @@ -35,7 +35,18 @@ From a command prompt, you can install it in a conda environment inside Anaconda .. code-block:: bash conda install git - pip install --upgrade git+https://github.com/jparisu/IArena.git@v0.2 + pip install --upgrade git+https://github.com/jparisu/IArena.git + + +=========================== +Install with pip +=========================== + +To install the package with ``pip``, you can use the following command: + +.. code-block:: bash + + pip install --upgrade git+https://github.com/jparisu/IArena.git =========== @@ -43,5 +54,3 @@ Coming soon =========== - Installation from source -- Installation via ``pip`` -- Installation via ``conda`` diff --git a/docs/src/infraestructure.rst b/docs/src/infraestructure.rst deleted file mode 100644 index 1b47971..0000000 --- a/docs/src/infraestructure.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _infrastructure: - -############## -Infrastructure -############## - -.. warning:: - - Coming soon. diff --git a/docs/src/players/players.rst b/docs/src/players/players.rst index 49e306e..edd301c 100644 --- a/docs/src/players/players.rst +++ b/docs/src/players/players.rst @@ -12,9 +12,16 @@ IPlayer ======= The interface can be found in ``src/IArena/interfaces/IPlayer`` module. - This interface is used by an *arena* to play a specific set of rules. -The only method that must be implemented is ``play``. + +------- +Methods +------- + +``play`` +^^^^^^^^ + +The only **required** method that must be implemented is ``play``. It receives an ``IPosition`` and must return an ``IMovement`` (specific movement depending on the rules playing). .. code-block:: python @@ -24,8 +31,27 @@ It receives an ``IPosition`` and must return an ``IMovement`` (specific movement position: IPosition) -> IMovement: pass -The constructor of an ``IPlayer`` is not defined. -Each implementation could have its own constructor, adding for example a name, the rules of the game, etc. +``name`` +^^^^^^^^ + +There is a method ``name`` that returns a string with the name of the player. +The default constructor has the argument ``name`` that sets the internal ``_name`` attribute. + +``starting_game`` +^^^^^^^^^^^^^^^^^ + +The method ``starting_game`` is called by the ``arena`` when the game starts. +It is useful to set, for example, the index of the player in the game. + + +.. code-block:: python + + def starting_game( + self, + rules: IGameRules, + player_index: int): + pass + ----- Rules @@ -91,105 +117,3 @@ If you prefer to see step by step the game playing by the player, use ``Broadcas players=[my_player] ) score = arena.play() - - -================= -Multiplayer games -================= - -In games with more than 1 player, you would need another player to play against. -There are several generic players implemented, please check :ref:`random_player`. - - -.. code-block:: python - - from IArena.arena.GenericGame import GenericGame # or BroadcastGame - from IArena.games.Coins import CoinsRules, CoinsMovement, CoinsPosition - from IArena.players.players import RandomPlayer - - rules = CoinsRules() - my_player = MyPlayer() - other_player = RandomPlayer() - - arena = GenericGame( - rules=rules, - players=[my_player, other_player] - ) - score = arena.play() - -You may want to repeat the game several times to get a better score. -For this purpose just use a loop and accumulate the score. - -.. code-block:: python - - from IArena.arena.GenericGame import GenericGame # or BroadcastGame - from IArena.games.Coins import CoinsRules, CoinsMovement, CoinsPosition - from IArena.players.players import RandomPlayer - from IArena.interfaces.ScoreBoard import ScoreBoard - - rules = CoinsRules() - my_player = MyPlayer() - other_player = RandomPlayer() - - score = ScoreBoard() - for _ in range(50): - arena = GenericGame( - rules=rules, - players=[my_player, other_player] - ) - score.join(arena.play()) - - print(f"When starting: {score}") - - score = ScoreBoard() - for _ in range(50): - arena = GenericGame( - rules=rules, - players=[other_player, my_player] - ) - score.join(arena.play()) - - print(f"When second: {score}") - - -================ -Heuristic Player -================ - -Other way to create a player is to give a heuristic for a position, rather than a movement. -The already implement player ``HeuristicPlayer`` does check every possible future position, -by trying every possible movement in a position, -and calculates the score of the position by the method ``heuristic``. -Then, it decides the movement with the lower heuristic. - -.. code-block:: python - - from IArena.arena.GenericGame import GenericGame # or BroadcastGame - from IArena.games.Hanoi import HanoiRules, HanoiMovement, HanoiPosition - from IArena.players.HeuristicPlayer import HeuristicPlayer - - class MyPlayer(HeuristicPlayer): - - def heuristic(self, position: HanoiPosition) -> float: - # Add code to calculate the heuristic of the position - return 0.0 - - rules = HanoiRules() - my_player = MyPlayer() - - arena = GenericGame( - rules=rules, - players=[my_player] - ) - - -.. note:: - - Remember that the best movement is the one with the lowest heuristic. - -Multiplayer game heuristic player ---------------------------------- - -One thing to take into account is that creating an heuristic for a multiplayer game, -the heuristic must be calculated as the position given is the one that the opponent will play. -Because the positions in which it applies are the next ones, and not the current ones. diff --git a/docs/src/titlepage.rst b/docs/src/titlepage.rst index c571b10..75dd614 100644 --- a/docs/src/titlepage.rst +++ b/docs/src/titlepage.rst @@ -1,4 +1,3 @@ -.. _title: #################### IArena Documentation