Update docs (#12)

* Add documentation for the Trick object and update usage sections in README

* Add initial documentation for wzrdbrain library

* Add API reference and usage documentation for wzrdbrain library

* Add disclaimer about AI coding assistant tools in contributors section

* Add API reference for the Trick object and update links in documentation

* Enhance contribution guidelines and credits section in documentation

* Add documentation for generating trick combos in Python and JavaScript

* Update credits section and add disclosure about AI coding assistant tools

* Add documentation for the JavaScript translation process using translate2js.py

* Refactor documentation for translate2js.py: improve clarity and consistency in section headings and descriptions

* Add link to Python to JavaScript translation documentation and correct credits section

* Refactor documentation: standardize headings and improve clarity in API reference and index files

* Fix heading level for "Maintainers & contributors" section in index.md

* Fix link in Table of contents for "Maintainers & contributors" section

* Bump version to 0.1.6 and fix package-data syntax in pyproject.toml

* Refactor documentation: standardize heading capitalization and improve clarity in CONTRIBUTING.md, GEMINI.md, README.md, and index.md

* Update import paths in documentation for JavaScript usage and refine section headings for clarity

* Update CI workflow and documentation for JavaScript output file renaming and path adjustments

* Fix package_data syntax in pyproject.toml by removing duplicate entry

* Add pyproject.toml to CI workflow path triggers

* Move package_data definition under [tool.setuptools] section in pyproject.toml

* chore: update src/wzrdbrain/wzrdbrain.js via utils/translate2js.py [skip ci]

* delete: remove wzrdbrain.src.js file and its associated logic

* docs: update README.md to clarify library usage and remove outdated examples

* docs: refine credits section for clarity and remove duplicate entries

* docs: update API reference and usage documentation for clarity and organization

* docs: add table of contents to usage documentation for improved navigation

* delete: remove CODE_OF_CONDUCT.md as it is no longer applicable

* docs: add Contributor Covenant statement to contributing guidelines

* docs: update Contributor Covenant link in contributing guidelines

* bump version to 0.2 in pyproject.toml

* chore: update src/wzrdbrain/wzrdbrain.js via utils/translate2js.py [skip ci]

* docs: improve clarity in project description and usage of libraries

* Update docs/usage.md

* docs: update references to the generated JavaScript file name in documentation

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/workflows/ci.yml

@@ -7,9 +7,11 @@ on:
   push:
     branches: ["**"]
     paths:
+      - 'utils/translate2js.py'
       - 'src/wzrdbrain/wzrdbrain.py'
       - 'src/wzrdbrain/tricks.json'
       - '.github/workflows/ci.yml'
+      - 'pyproject.toml'
 
 jobs:
   test:
@@ -59,21 +61,21 @@ jobs:
 
       - name: Show first lines of generated file
         run: |
-          echo "Preview of src/wzrdbrain/wzrdbrain.src.js:"
-          head -n 60 src/wzrdbrain/wzrdbrain.src.js || true
+          echo "Preview of src/wzrdbrain/wzrdbrain.js:"
+          head -n 60 src/wzrdbrain/wzrdbrain.js || true
       - name: Detect changes in generated file
         id: diff
         shell: bash
         run: |
-          # Determine if src/wzrdbrain/wzrdbrain.src.js is new or modified
-          if git ls-files --error-unmatch src/wzrdbrain/wzrdbrain.src.js >/dev/null 2>&1; then
-            if git diff --quiet -- src/wzrdbrain/wzrdbrain.src.js; then
+          # Determine if src/wzrdbrain/wzrdbrain.js is new or modified
+          if git ls-files --error-unmatch src/wzrdbrain/wzrdbrain.js >/dev/null 2>&1; then
+            if git diff --quiet -- src/wzrdbrain/wzrdbrain.js; then
               echo "changed=false" >> "$GITHUB_OUTPUT"
             else
               echo "changed=true" >> "$GITHUB_OUTPUT"
             fi
           else
-            if [ -f src/wzrdbrain/wzrdbrain.src.js ]; then
+            if [ -f src/wzrdbrain/wzrdbrain.js ]; then
               echo "changed=true" >> "$GITHUB_OUTPUT"
             else
               echo "changed=false" >> "$GITHUB_OUTPUT"
@@ -84,7 +86,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: wzrdbrain-js
-          path: src/wzrdbrain/wzrdbrain.src.js
+          path: src/wzrdbrain/wzrdbrain.js
 
       - name: Commit generated file to working branch
         if: steps.diff.outputs.changed == 'true'
@@ -93,6 +95,6 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -B "$branch"
-          git add src/wzrdbrain/wzrdbrain.src.js
-          git commit -m "chore: update src/wzrdbrain/wzrdbrain.src.js via utils/translate2js.py [skip ci]"
+          git add src/wzrdbrain/wzrdbrain.js
+          git commit -m "chore: update src/wzrdbrain/wzrdbrain.js via utils/translate2js.py [skip ci]"
           git push origin "$branch"

CODE_OF_CONDUCT.md

@@ -2,23 +2,25 @@
 
 First off, thank you for considering contributing!
 
-## Submitting Changes
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating in this project, you agree to uphold this code.
+
+## Submitting changes
 
 1.  Create a new branch for your feature or bug fix.
 2.  Make your changes and commit them.
 3.  Use clear, concise messages (e.g., feat: add X, fix: correct Y).
 4.  Ensure all quality checks pass.
 5.  Push your branch and open a pull request.
 
-## Contributing a New Trick
+## Contributing a new move or trick
 
 We welcome contributions of new tricks to the library! The list of tricks is managed in the `src/wzrdbrain/tricks.json` file.
 
 To add a new trick, follow these steps:
 
-1.  **Open `src/wzrdbrain/tricks.json`**.
-2.  **Add your trick to the `MOVES` list**. Please keep the list in alphabetical order.
-3.  **Update the `RULES` if necessary**. If your trick has special properties, you may need to add it to one of the lists in the `RULES` section:
+1.  Open `src/wzrdbrain/tricks.json`.
+2.  Add your trick to the `MOVES` list. Please keep the list in alphabetical order.
+3.  Update the `RULES` if necessary. If your trick has special properties, you may need to add it to one of the lists in the `RULES` section:
     *   `ONLY_FIRST`: Moves that can only appear as the first trick in a combo.
     *   `USE_FAKIE`: Moves that should be prefixed with "fakie" instead of "back".
     *   `EXCLUDE_STANCE_BASE`: Moves that do not have a stance (e.g., "open", "closed").
@@ -28,7 +30,7 @@ After making your changes, be sure to run the test suite to ensure everything is
 
 Once you have verified your changes, please see the "Submitting Changes" section for instructions on how to open a pull request.
 
-## Development Setup
+## Development setup
 
 To get started with development, follow these steps:
 
@@ -50,11 +52,11 @@ To get started with development, follow these steps:
     pip install -e ".[dev]"
     ```
 
-## Running Quality Checks
+## Running quality checks
 
 Before submitting a pull request, please ensure your code passes all quality checks.
 
-### Linting and Formatting
+### Linting and formatting
 
 We use `ruff` for linting and `black` for formatting.
 
@@ -66,15 +68,15 @@ ruff check .
 black .
 ```
 
-### Type Checking
+### Type checking
 
 We use `mypy` for static type checking.
 
 ```bash
 mypy .
 ```
 
-### Running Tests
+### Running tests
 
 We use `pytest` for running unit tests.
 

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Gemini Code Understanding
+
+This document provides a summary of the `wzrdbrain` project, generated by Gemini.
+
+## Project Summary
+
+`wzrdbrain` is a Python library designed to generate random trick combinations for wizard skating. It can create sequences of tricks, ensuring that the transitions between them are logical. Users can also create individual tricks with specific attributes. The project also includes a JavaScript version of the library, which is automatically generated from the Python source code. The current version of the project is 0.1.6.
+
+## Key Files
+
+- **`pyproject.toml`**: The project's configuration file, defining metadata, dependencies, and development settings.
+- **`src/wzrdbrain/wzrdbrain.py`**: The core of the library, containing the logic for generating trick combinations in Python.
+- **`src/wzrdbrain/tricks.json`**: A JSON file that defines the available wizard skating tricks, including their names, stances, and transition rules.
+- **`tests/test_wzrdbrain.py`**: The test suite for the project, ensuring that the trick generation logic works as expected.
+- **`utils/translate2js.py`**: A utility script to translate the Python trick data and logic into a JavaScript-compatible format.
+- **`src/wzrdbrain/wzrdbrain.js`**: The generated JavaScript version of the library.
+- **`utils/wzrdbrain.base.js`**: A JavaScript file that contains the base logic for the JavaScript version of the library, used as a reference for the translation script.
+
+## How to Use (Python)
+
+As described in the `README.md`, you can use the `generate_combo` function to get a list of random tricks:
+
+```python
+from wzrdbrain import generate_combo
+
+# Generate a combo of 3 tricks
+combo = generate_combo(3)
+
+# Get the names of the tricks
+trick_names = [trick['name'] for trick in combo]
+print(trick_names)
+```
+
+## How to Use (JavaScript)
+
+The generated JavaScript module can be used in any JavaScript environment that supports ES6 modules.
+
+```javascript
+import { generateCombo } from 'https://cdn.jsdelivr.net/gh/nazroll/wzrdbrain/src/wzrdbrain/wzrdbrain.min.js';
+
+// Generate a combo of 3 tricks
+const combo = generateCombo(3);
+
+// Get the names of the tricks
+const trickNames = combo.map(trick => trick.name);
+console.log(trickNames);
+```
+
+## Project Purpose
+
+The main goal of this project is to provide a tool for wizard skaters to come up with new and creative trick combinations. By randomizing the sequence of tricks, it can help skaters break out of their usual patterns and discover new possibilities. The project also aims to provide a JavaScript version of the library for use in web-based applications.
+
+## Recent Changes
+
+The project has been recently updated to version 0.1.6. This update includes a fix for the `package_data` syntax in the `pyproject.toml` file, ensuring that the `tricks.json` file is correctly included in the package. There have also been a number of documentation updates to improve clarity and consistency.

GEMINI.md

@@ -1,82 +1,72 @@
 # wzrdbrain
 
-A library to generate random trick combinations for wizard skating.
+A library to generate random trick combinations for wizard skating. This library is available in Python and JavaScript versions.
+
+[Rocker'd Magic Moves](https://rockerd.web.app) - a trick generator app for wizard skating, is using both libraries.
+
+The mobile web app is utilizing the JavaScript library version. It runs offline.
+
+The [Rocker'd](https://rockerd.web.app) RESTFul API endpoints is using the Python library. Read the [API docs](https://rockerd.web.app/api/docs). 
+
+## Usage
+
+### Python
 
-## Installation
 
 ```bash
 pip install wzrdbrain
 ```
 
-## Usage
-
 The primary function is `generate_combo`, which returns a list of trick dictionaries. You can also create `Trick` objects directly for more control.
 
 ```python
 from wzrdbrain import generate_combo, Trick
 
 # Generate a combo of 3 tricks
-combo = generate_combo(3)
-
-# The output is a list of dictionaries, each representing a trick
-# print(combo)
-# Example output:
-# [
-#     {
-#         'direction': 'front', 'stance': 'open', 'move': 'gazelle', 
-#         'enter_into_trick': 'front', 'exit_from_trick': 'back', 
-#         'name': 'front open gazelle'
-#     },
-#     {
-#         'direction': 'back', 'stance': None, 'move': '360', 
-#         'enter_into_trick': 'back', 'exit_from_trick': 'back', 
-#         'name': 'fakie 360'
-#     },
-#     # ... and so on
-# ]
-
 # To get just the names of the tricks in the combo:
+combo = generate_combo(3)
 trick_names = [trick['name'] for trick in combo]
 print(trick_names)
 # Example output: ['front open gazelle', 'fakie 360', 'back open lion']
+#
 ```
 
-### Creating a Trick Object
-
-You can create a `Trick` object with specific attributes. Any attributes not provided will be randomly generated.
+### JavaScript
 
-```python
-# Create a trick with a specific move
-my_trick = Trick(move="lion s")
-
-# Print the full trick object as a dictionary
-print(my_trick.to_dict())
-# Example output:
-# {
-#     'direction': 'back', 'stance': 'closed', 'move': 'lion s', 
-#     'enter_into_trick': 'back', 'exit_from_trick': 'back', 
-#     'name': 'back closed lion s'
-# }
+```
+https://cdn.jsdelivr.net/gh/nazroll/wzrdbrain/src/wzrdbrain/wzrdbrain.min.js
 ```
 
-## Development
+This library also provides a JavaScript version of the trick generation logic, which can be used in any environment that supports ES6 modules.
 
-To contribute to this project, please see the [Contributing Guide](CONTRIBUTING.md).
+```javascript
+import { generateCombo } from 'https://cdn.jsdelivr.net/gh/nazroll/wzrdbrain/src/wzrdbrain/wzrdbrain.min.js';
 
-First, clone the repository and install the project in editable mode with its development dependencies:
+// Generate a combo of 3 tricks
+const combo = generateCombo(3);
 
-```bash
-git clone https://github.com/nazroll/wzrdbrain.git
-cd wzrdbrain
-pip install -e .[dev]
+// Get the names of the tricks
+const trickNames = combo.map(trick => trick.name);
+console.log(trickNames);
 ```
 
-You can run the test suite using `pytest`:
+For more examples, read the [usage documentation](./docs/usage.md).
 
-```bash
-pytest
-```
+## Contribution
+
+We welcome contributions! `wzrdbrain` is fully open source (Apache 2.0), and we encourage the community to:
+
+- Submit a new move/trick into the database.
+- Report bugs and suggest features
+- Improve documentation
+- Submit code improvements
+
+To contribute to this project, please read the [contributing guide](CONTRIBUTING.md).
+
+## Credits
 
-## List of wizard skating tricks
+Many thanks to the skaters and the wizard skating community for their valuable feedback and support. Special thanks to:
 
-The list of tricks in this library is not comprehensive. Please create an issue and give us your suggestions of new tricks
+- Billy Arlew: for being a reliable source of inspiration and domain knowledge to the wizard tricks dictionary.
+- Eelco Soesman: for being a supportive Slightly Rockerd crew and early tester.
+- Bas Bavinck: for being the beacon of wizardry with his book and supporting this project.

README.md

@@ -0,0 +1,54 @@
+# Welcome to wzrdbrain
+
+`wzrdbrain` is a library for generating random trick combinations for wizard skating. This documentation provides a guide for developers who want to use and contribute to the project.
+
+## Table of contents
+
+- [About the project](#about-the-project)
+- [Maintainers & contributors](#maintainers--contributors)
+- [Getting started](./usage.md)
+  - [Python usage](./usage.md#python-usage)
+  - [JavaScript usage](./usage.md#javascript-usage)
+  - [API reference](usage.md#api-reference)
+    - [The Trick object](./usage.md#the-trick-object)
+    - [Generating trick combos](./usage.md#generating-trick-combos)
+- [Python-to-JS code translation](#python-to-js-code-translation)
+- [Credits](#credits)
+
+
+## About the project
+
+`wzrdbrain`  is designed to help wizard skaters discover new trick combinations. By randomizing the sequence of tricks, it can help skaters break out of their usual patterns. 
+
+The project provides both a Python and a JavaScript version of the library.
+
+The JavaScript version is automatically generated from the Python source code using a translation script that leverages the Google Gemini API.
+
+## Maintainers & contributors
+
+[![contributors](https://contrib.rocks/image?repo=nazroll/wzrdbrain)](https://github.com/nazroll/wzrdbrain/graphs/contributors)
+
+_**Disclosure:** AI coding assistant tools like Google Gemini CLI, Jules by Google and Github Copilot are used in this project._
+
+## Getting started
+
+For developers, read [usage.md](./usage.md) to learn how to install and use the library in Python and JavaScript.
+
+## API reference
+
+For more detailed information about the data structures used in `wzrdbrain`, please refer to the following documents:
+
+- [The Trick object](./api_reference.md#the-trick-object)
+- [Generating trick combos](./api_reference.md#generating-trick-combos)
+
+## Python-to-JS code translation
+
+The JavaScript version of the library (`src/wzrdbrain/wzrdbrain.js`) is automatically generated from the Python source code. For more details on this process, read [Translating Python code to JavaScript code](./translate2js.md).
+
+## Credits
+
+Many thanks to the skaters and the wizard skating community for their valuable feedback and support. Special thanks to:
+
+- Billy Arlew: for being a reliable source of inspiration and domain knowledge to the wizard tricks dictionary.
+- Eelco Soesman: for being a supportive Slightly Rockerd crew and early tester.
+- Bas Bavinck: for being the beacon of wizardry with his book and supporting this project.