Merge pull request #5 from xAlessandroC/doc/gh-pages

Doc/gh pages

.github/workflows/pages.yml

@@ -0,0 +1,69 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    paths:
+      - "docs/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1' # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+          working-directory: '${{ github.workspace }}/docs'
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "docs/_site/"
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -158,3 +158,15 @@ 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/
+
+
+# Ignore the default location of the built site, and caches and metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/
+

docs/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.2" # installed by `gem jekyll`
+# gem "webrick"        # required when using Ruby >= 3 and Jekyll <= 4.2.2
+
+gem "just-the-docs", "0.7.0" # pinned to the current release
+# gem "just-the-docs"        # always download the latest release

docs/Gemfile.lock

@@ -0,0 +1,85 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.5)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.2)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    google-protobuf (3.24.3-arm64-darwin)
+    google-protobuf (3.24.3-x86_64-linux)
+    http_parser.rb (0.8.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.7.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.3)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.1.3)
+    safe_yaml (1.0.5)
+    sass-embedded (1.67.0-arm64-darwin)
+      google-protobuf (~> 3.23)
+    sass-embedded (1.67.0-x86_64-linux-gnu)
+      google-protobuf (~> 3.23)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.4.2)
+    webrick (1.8.1)
+
+PLATFORMS
+  arm64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll (~> 4.3.2)
+  just-the-docs (= 0.7.0)
+
+BUNDLED WITH
+   2.3.26

docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 just-the-docs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/_config.yml

@@ -0,0 +1,8 @@
+title: Conway Game of Life
+description: A quadtree-based Conway's Game of Life using Python and Flask.
+theme: just-the-docs
+
+url: https://xalessandroc.github.io/ConwayGameOfLife/
+
+aux_links:
+  Template Repository: https://github.com/just-the-docs/just-the-docs-template

docs/index.md

@@ -0,0 +1,96 @@
+---
+title: Home
+layout: home
+---
+
+# Conway's Game of Life
+{: .fs-9 }
+
+These brief instructions will help you get started with the tool. 
+{: .fs-6 .fw-300 }
+
+[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View it on GitHub][UPS repo]{: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+# Overview
+The project aims to realize a custom implementation of the famous Conway's Game of Life automata as web server by using Python and Flask.
+The service can be run directly through the repo os by using the Docker image available in the GitHub registry.
+
+For more details check the [Get started now](#getting-started) section.
+
+# Conway's Game of Life
+The Game of Life, also known simply as Life, is a cellular automaton devised by the British mathematician John Horton Conway in 1970 and demonstrated to be Turing complete.
+The game is a zero-player game, meaning that its evolution is determined by its initial state, requiring no further input.
+One interacts with the Game of Life by creating an initial configuration and observing how it evolves.
+
+The universe of the Game of Life is a two-dimensional orthogonal grid of square cells, each of which is in one of two possible states, alive or dead, or "populated" or "unpopulated".
+Every cell interacts with its eight neighbours, which are the cells that are horizontally, vertically, or diagonally adjacent.
+At each step in time, the following rules, which compare the behaviour of the automaton to real life, occur:
+1) Any live cell with fewer than two live neighbours dies, as if by underpopulation.
+2) Any live cell with two or three live neighbours lives on to the next generation.
+3) Any live cell with more than three live neighbours dies, as if by overpopulation.
+4) Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction.
+
+The initial pattern constitutes the seed of the system.
+The first generation is created by applying the above rules simultaneously to every cell in the seed; births and deaths occur simultaneously, and the discrete moment at which this happens is sometimes called a tick.
+Each generation is a pure function of the preceding one.
+
+Since its publication, the Game of Life has attracted much interest because of the surprising ways in which the patterns can evolve.
+Many different types of patterns occur in the Game of Life, which are classified according to their behaviour. Common pattern types include still lifes, which do not change from one generation to the next, oscillators, which return to their initial state after a finite number of generations and spaceships, which translate themselves across the grid.
+
+Still Lifes            |  Oscillators          |  Spaceship
+:-------------------------:|:-------------------------:|:-------------------------:
+![](https://upload.wikimedia.org/wikipedia/commons/thumb/f/f4/Game_of_life_loaf.svg/98px-Game_of_life_loaf.svg.png)  |  ![](https://upload.wikimedia.org/wikipedia/commons/1/12/Game_of_life_toad.gif) |  ![](https://upload.wikimedia.org/wikipedia/commons/f/f2/Game_of_life_animated_glider.gif)
+
+
+
+# Quadtree application
+In a common implementation of the Game of Life automata, each cell is explored to update it for the next generation, even if it remains in the same state. However, according to the rules of the automata, it is unnecessary to control cells that do not have any living cells in a certain range around them. This is why indexing techniques are often used to optimize the process. This Conway's Game of Life project relies on the quadtree indexing technique to efficiently update the cells.
+Quadtrees are a tree data structure in which each internal node has exactly four children. Quadtrees are most often used to partition a two-dimensional space by recursively subdividing it into four quadrants or regions. The regions may be square or rectangular.
+
+In this application, the grid constitutes the root of the tree and each time a new cell is added, the tree is subdivided into four quadrants. The subdivision is repeated until the maximum number of cells per quadrant is reached.
+Then, the tree structure can be easily queried to retrieve all the quadrants which contains active cells. This way, the number of cells to be explored is always minimized favouring a faster execution of the generations. This is particularly usefull when the number of alive cell is high and the grid is sparse.
+
+
+# Getting Started
+There are two possibilities to run the service properly
+
+### Python Web Server
+To run the service locally, you need to install the requirements
+```bash
+git clone https://github.com/xAlessandroC/ConwayGameOfLife
+pip install -r requirements.txt
+```
+
+Finally run the server
+```bash
+cd gameoflife
+flask --app app --debug run --host <IP> --port <PORT>
+```
+
+The application should be available at the following address: http://\<IP>:\<PORT>/
+
+### Docker Image
+An already-configured Docker image is available in the GitHub registry. To run the service, you need to pull the image and run it.
+```bash
+docker pull ghcr.io/xalessandroc/game-of-life:latest
+docker run -p <PORT>:5000 ghcr.io/xalessandroc/game-of-life:latest
+```
+
+The application should be available at the following address: http://\<IP>:\<PORT>/
+
+# How to Use
+The application is composed by a single main page
+
+![](../docs/images/mainpage.png)
+
+The main page is composed by a grid and a control panel. The grid is used to visualize the current state of the automata and the control panel is used to interact with the automata. On the top of the page are also displayed information related to the FPS metric and the number of the current generation.
+The control panel is composed by the following elements:
+- **Next**: This button is used to compute the next generation of the automata
+- **SetAutomatic**: This button is used to start the automatic computation of the generations. To stop the automatic computation, the button must be pressed again.
+- **Pattern Menu**: This menu allows for the selection of pattern to insert in the grid to check the evolution in time.
+
+
+# How to Cite