📓 add readme s

Author: Platane

.gitignore

@@ -2,5 +2,4 @@ node_modules
 npm-debug.log*
 yarn-error.log*
 dist
-build
-out.gif
+build

README.md

@@ -3,10 +3,39 @@
 ![type definitions](https://img.shields.io/npm/types/typescript?style=flat-square)
 ![code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)
 
+Generates a snake game from a github user contributions grid
+
 ![](https://raw.githubusercontent.com/Platane/snk/output/github-contribution-grid-snake.gif)
 
-Generates a snake game from a github user contributions grid and output a screen capture as gif
+Pull a github user's contribution grid.
+Make it a snake Game, generate a snake path where the cells get eaten in an orderly fashion.
+
+Generate a [gif](https://github.com/Platane/snk/raw/output/github-contribution-grid-snake.gif) or [svg](https://github.com/Platane/snk/raw/output/github-contribution-grid-snake.svg) image.
+
+Available as github action. Automatically generate a new image at the end of the day. Which make for great [github profile readme](https://docs.github.com/en/free-pro-team@latest/github/setting-up-and-managing-your-github-profile/managing-your-profile-readme)
+
+## Usage
+
+**github action**
+
+```yaml
+- uses: Platane/snk@master
+  with:
+    github_user_name: platane
+    gif_out_path: dist/github-contribution-grid-snake.gif
+    svg_out_path: dist/github-contribution-grid-snake.svg
+```
+
+> [example with cron job](https://github.com/Platane/Platane/blob/master/.github/workflows/main.yml#L13-L18)
+
+**interactive demo**
+
+[platane.github.io/snk](https://platane.github.io/snk)
+
+**local**
 
-- [demo](https://platane.github.io/snk)
+```
+npm install
 
-- [github action](https://github.com/marketplace/actions/generate-snake-game-from-github-contribution-grid)
+npm run dev:demo
+```

action.yml

@@ -1,12 +1,12 @@
 name: "generate-snake-game-from-github-contribution-grid"
-description: "Generates a snake game from a github user contributions grid and output a screen capture as gif"
+description: "Generates a snake game from a github user contributions grid. Output the animation as gif or svg"
 author: "platane"
 
 outputs:
   gif_out_path:
-    description: "path of the generated gif"
+    description: "path of the generated gif. If left empty, will not generate a gif file"
   svg_out_path:
-    description: "path of the generated svg"
+    description: "path of the generated svg. If left empty, will not generate a svg file"
 
 runs:
   using: "docker"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "snk",
-  "description": "Generates a snake game from a github user contributions grid and output a screen capture as gif",
+  "description": "Generates a snake game from a github user contributions grid",
   "version": "1.0.0",
   "private": true,
   "repository": "github:platane/snk",

packages/action/README.md

@@ -0,0 +1,15 @@
+# @snk/action
+
+Contains the github action code.
+
+## Implementation
+
+### Docker
+
+Because the gif generation requires some native libs, we cannot use a node.js action.
+
+Use a docker action instead, the image is created from the [Dockerfile](./Dockerfile).
+
+It's published to [dockerhub](https://hub.docker.com/repository/docker/platane/snk) which makes for faster build ( compare to building the image when the action runs )
+
+Notice that the [action.yml](../../action.yml) point to the latest version of the image. Which makes releasing sematic versioning of the action pointless. Which is probably fine for a wacky project like this one.

packages/compute/README.md

@@ -0,0 +1,33 @@
+# @snk/compute
+
+Contains the algorithm to compute the best route given a grid and a starting position for the snake.
+
+## Implementation
+
+- for each color in the grid
+
+- 1\ **clear residual color** phase
+
+  - find all the cells of a previous color that are "tunnel-able" ( ie: the snake can find a path from the outside of the grid to the cell, and can go back to the outside without colliding ). The snake is allowed to pass thought current and previous color. Higher colors are walls
+
+  - sort the "tunnel-able" cell, there is penalty for passing through current color, as previous color should be eliminated as soon as possible.
+
+  - for cells with the same score, take the closest one ( determined with a quick mathematic distance, which is not accurate but fast at least )
+
+  - navigate to the cell, and through the tunnel.
+
+  - re-compute the list of tunnel-able cells ( as eating cells might have freed better tunnel ) as well as the score
+
+  - iterate
+
+- 2\ **clear clean color** phase
+
+  - find all the cells of the current color that are "tunnel-able"
+
+  - no need to consider scoring here. In order to improve efficiency, get the closest cell by doing a tree search ( instead of a simple mathematic distance like in the previous phase )
+
+  - navigate to the cell, and through the tunnel.
+
+  - iterate
+
+- go back to the starting point

packages/demo/README.md

@@ -0,0 +1,3 @@
+# @snk/demo
+
+Contains various demo to test and validate some pieces of the algorithm.

packages/draw/README.md

@@ -0,0 +1,3 @@
+# @snk/draw
+
+Draw grids and snakes on a canvas.

packages/gif-creator/README.md

@@ -0,0 +1,5 @@
+# @snk/gif-creator
+
+Generate a gif file from the grid and snake path.
+
+Relies on graphics magic and gifsicle binaries.

packages/github-user-contribution-service/README.md

@@ -0,0 +1,3 @@
+# @snk/github-user-contribution-service
+
+Expose github-user-contribution as an endpoint, using vercel.sh

packages/github-user-contribution/README.md

@@ -0,0 +1,7 @@
+# @snk/github-user-contribution
+
+Get the github user contribution grid
+
+## Implementation
+
+Based on the html page. Which is very unstable. Might switch to using github api but afaik it's a bit complex.

packages/svg-creator/README.md

@@ -0,0 +1,5 @@
+# @snk/svg-creator
+
+Generate a svg file from the grid and snake path.
+
+Uses css style tag to animate the snake and the grid cells. For that reason it only work in browser. Animations are likely to be ignored be native image reader.

packages/types/README.md

@@ -0,0 +1,3 @@
+# @snk/types
+
+set of basic types and helpers