Merge pull request #4 from Jtachan/release/v1.0.0

Release/v1.0.0

Author: Jtachan

gh_actions/workflows/linters.yml .github/workflows/linters.ymlgh_actions/workflows/linters.yml renamed to .github/workflows/linters.yml

@@ -12,19 +12,19 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python 3.8
+      - name: Set up Python 3.9
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.9
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r dev_requirements.txt
+          pip install flake8==6.0.* pylint==2.17.* black==23.7.0 isort==5.12.* pytest
       - name: Run linters
         run: |
-          isort --check enigma_cipher setup.py unittests
-          black --check enigma_cipher setup.py unittests
+          isort --check src unittests
+          black --check src unittests
           pip install .
-          flake8 --tee --format=pylint enigma_cipher unittests
-          pylint --rcfile=pylintrc enigma_cipher unittests
+          flake8 --tee --format=pylint src unittests
+          pylint --rcfile=pylintrc src unittests

gh_actions/workflows/unittests.yml .github/workflows/unittests.ymlgh_actions/workflows/unittests.yml renamed to .github/workflows/unittests.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v3

.gitignore

@@ -153,8 +153,8 @@ dmypy.json
 cython_debug/
 
 # PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  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/
+.idea/
+
+# Dev files
+check_pkg.bat
+dev_requirements.txt

MANIFEST.in

@@ -0,0 +1,4 @@
+# package all files within the src directory
+graft src
+# exclude all bytecode files
+global-exclude *.py[cod]

README.md

@@ -1,31 +1,93 @@
-![tests_badge](https://github.com/Jtachan/{REPO}/actions/workflows/unittests.yml/badge.svg)
+![tests_badge](https://github.com/Jtachan/Rubik_sim/actions/workflows/unittests.yml/badge.svg)
 
-# Rubik's Cube Solver
+# Rubik Sim
 
-This project displays a Rubik's cube solver created with genetic algorithms.
+This project allows to simulate a 3x3 Rubik's cube and perform operations over it.
 
-## 📖 Documentation
-
-Documentation will be added once the project advances.
-Feel free to look for the latest updates within the 'develop' branch.
-
-## 🐍 Python Setup
+## ⚙️ Setup
 
 **Requirements**
 
-- Python 3.8 or higher
+- Python 3.9 or higher
 
 **Installation**
 
-The package is not released in PyPI. Thus, there are multiple options to run the code:
+The package is installable via pip:
 
-1. Install via pip + git
 ````shell
-pip install git+https://github.com/Jtachan/genetic_rubiks_solver.git
+pip install rubik-sim
 ````
 
-2. Clone the repo, then install locally
+Alternatively, the 'develop' branch can be installed for the latest changes
 ```shell
-git clone https://github.com/Jtachan/genetic_rubiks_solver.git
-pip install .
+pip install git+https://github.com/Jtachan/genetic_rubiks_solver.git@develop
+```
+
+## 🏃 Usage 
+
+#### Initializing the cube
+
+The package allows importing all the classes directly from the module. 
+
+To initialize the cube, it is only needed the `RubiksCube` class.
+This generates a fully solved cube. To obtain a random state using `scramble()` 
+
+````python
+from rubik_sim import RubiksCube
+
+my_cube = RubiksCube()  # Solved cube
+my_cube.scramble()  # Updates the cube by 25 random moves
+````
+
+The number of moves to scramble the cube can also be specified as a parameter:
+<br/>`RubiksCube.scramble(nof_moves: int = 25)`
+
+It is also possible to initialize any cube from a string of characters defining the color of each tile.
+
+````python
+my_cube = RubiksCube.from_color_code(
+    'BBBBBBBBBGGGGGGGGGOOOOOOOOOYYYYYYYYYRRRRRRRRRWWWWWWWWW'
+)
+````
+
+The only supported colors are green ('G'), orange ('O'), yellow ('Y'), red ('R'), white ('W') and blue ('B').
+
+#### Representation
+
+The cube's state can be represented by calling `print()`
+
+```pycon
+>>> print(my_cube)
+             ['B' 'B' 'B']
+             ['B' 'B' 'B']
+             ['B' 'B' 'B']
+['G' 'G' 'G']['O' 'O' 'O']['Y' 'Y' 'Y']['R' 'R' 'R']
+['G' 'G' 'G']['O' 'O' 'O']['Y' 'Y' 'Y']['R' 'R' 'R']
+['G' 'G' 'G']['O' 'O' 'O']['Y' 'Y' 'Y']['R' 'R' 'R']
+             ['W' 'W' 'W']
+             ['W' 'W' 'W']
+             ['W' 'W' 'W']
 ```
+
+From the representation, the faces are:
+
+- Blue = Top (up) face 
+- Green = Left face 
+- Orange = Front face 
+- Yellow = Right face 
+- Red = Back face 
+- White = Bottom (down) face 
+
+#### Rotating the cube
+
+`RubiksCube.perform_operations(operations: Sequence[NOTATION_MOVES])`
+
+This method updates the current state of the cube by performing operations over it.
+The supported operations are:
+> U, U', U2, D, D', D2, R, R', R2, L, L', L2, F, F', F2, B, B', B2,
+> M, M', M2, E, E', E2, S, S' and S2.
+ 
+These are the general notations for the possible moves on the cube.
+More about the Rubik's cube notation: https://ruwix.com/the-rubiks-cube/notation/
+
+Any missing notation can be performed with the current notations.