docs: update examples to show js and ts code (#203)

Author: nmerget

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Local Development
+# Contributing
 
 ## Project Structure
 
@@ -7,10 +7,24 @@ TODO
 ## Documentation
 
 This project uses [MKDocs](https://www.mkdocs.org/) to serve all docs. You can change the documentation inside the `docs` folder.
+Install mkdocs via ``pip install mkdocs``. 
+Serve the docs via ``mkdocs serve``.
 To add new pages you need to update `mkdocs.yml`.
 
 ## Preparing your PR
 
 The project is using [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) to format most files. You need to run `bash ./clang_format.sh` before your PR for a successful pipeline.
 
 Furthermore, there is an `utf-8` and `LF` checker to fix file formats. Additionally, some spellchecks run inside the [pipeline](.github/workflows/static_checks.yml).
+
+## Release library
+
+As a maintainer you are able to create a new release.
+1. Go to  [create new release](https://github.com/Geequlim/ECMAScript/releases/new)
+2. Next you should ``Choose a tag`` and create a new one in the format `v0.0.0`
+3. Select target ``master``
+4. Click ``Generate release notes``
+5. (Optional) You can edit the generated release notes
+6. Add a release title in the format ``[Godot_Version]-[Tag]-alpha-[Year][Month][Day]`` as an example ``4.1-v0.0.17-alpha-20231003``
+7. Press ``Publish release``
+

docs/examples/load-json-in-singleton.md

@@ -1,77 +1,117 @@
 # Load json in singleton
 
-This example shows how to load a file like a ``config`` inside a singleton to access it everywhere.
-We use ``TypeScript`` for this example all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`. If you use `TypeScript` you need to set `"resolveJsonModule": true` inside your `tsconfig.json`.
+This example shows how to load a file like a `config` inside a singleton to access it everywhere.
+
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
+
+> **Note:** If you use `TypeScript` you need to set `"resolveJsonModule": true` inside your `tsconfig.json`.
 
 ## 1. Create file
 
-We create a new folder named ``config`` and  a new file `test.json`.
+We create a new folder named `config` and a new file `test.json`.
 
-Next we write this to the ``test.json``:
+Next we write this to the `test.json`:
 
-````json title="test.json"
+```json title="test.json"
 {
   "test": true
 }
-````
+```
 
 ## 2. Create the singleton
 
-We create a new file inside our `src` folder like ``read-config.ts`` and add this code to it:
+We create a new file inside our `src` folder like `read-config.(mjs|ts)` and add this code to it:
 
-````ts title="read-config.ts"
-// @ts-ignore
-import TestJson from "res://config/test.json";
+=== "JavaScript"
 
-type TestType = {
-  test: boolean;
-};
+    ```javascript title="read-config.mjs"
+    import TestJson from "res://config/test.json";
 
-export default class ReadConfig extends godot.Node {
-  static _singleton: ReadConfig;
+    export default class ReadConfig extends godot.Node {
+      static _singleton;
 
-  static get singleton() {
-    return ReadConfig._singleton;
-  }
+      static get singleton() {
+    	return ReadConfig._singleton;
+      }
 
-  constructor() {
-    super();
-    if (!ReadConfig._singleton) {
-		ReadConfig._singleton = this;
+      constructor() {
+    	super();
+    	if (!ReadConfig._singleton) {
+    	  ReadConfig._singleton = this;
+    	}
+      }
+
+      // This property is available for other classes
+      config = TestJson;
     }
-  }
-  
-  // This property is available for other classes
-  config: TestType = TestJson as TestType;
-}
-````
+    ```
+
+=== "TypeScript"
+
+    ```ts title="read-config.ts"
+    // @ts-ignore
+    import TestJson from "res://config/test.json";
+
+    type TestType = {
+      test: boolean;
+    };
+
+    export default class ReadConfig extends godot.Node {
+      static _singleton: ReadConfig;
+
+      static get singleton() {
+    	return ReadConfig._singleton;
+      }
+
+      constructor() {
+    	super();
+    	if (!ReadConfig._singleton) {
+    	  ReadConfig._singleton = this;
+    	}
+      }
+
+      // This property is available for other classes
+      config: TestType = TestJson as TestType;
+    }
+    ```
 
 ## 3. Autoload singleton in project
 
-We need to update the ``[autoload]`` inside `project.godot`:
+We need to update the `[autoload]` inside `project.godot`:
 
-````text title="project.godot"
+```text title="project.godot"
 ...
 [autoload]
 
 ; Use the generated `.mjs` file instead of `.ts`
 ReadConfig="*res://scripts/generated/read-config.mjs"
 ...
-````
+```
 
 ## 4. Use the singleton in other class
 
-In another class e.g. ``main.ts`` you need to import the `ReadConfig` then you can access every public property and method from `ReadConfig` via `ReadConfig.singleton`:
+In another class e.g. `main.(mjs|ts)` you need to import the `ReadConfig` then you can access every public property and method from `ReadConfig` via `ReadConfig.singleton`:
 
-````ts title="main.ts"
-import ReadConfig from "./read-config";
+=== "JavaScript"
 
-export default class Main extends godot.Node {
-	_ready(): void {
-		console.log(ReadConfig.singleton.config.test); // prints "true"
-	}
-}
+    ```ts title="main.mjs"
+    import ReadConfig from "./read-config";
+
+    export default class Main extends godot.Node {
+      _ready() {
+    	console.log(ReadConfig.singleton.config.test); // prints "true"
+      }
+    }
+    ```
 
-````
+=== "TypeScript"
 
+    ```ts title="main.ts"
+    import ReadConfig from "./read-config";
 
+    export default class Main extends godot.Node {
+      _ready(): void {
+    	console.log(ReadConfig.singleton.config.test); // prints "true"
+      }
+    }
+    ```

docs/examples/read-file-local.md

@@ -2,7 +2,7 @@
 
 This example shows how to load any file as string from a local folder.
 
-We use ``TypeScript`` for this example all `.ts` files will be compiled as `.mjs`. 
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
 
 ## 1. Create the file you want to read
 
@@ -19,19 +19,36 @@ HELLO,hello,hallo
 
 We use [FileAccess](https://docs.godotengine.org/en/stable/classes/class_fileaccess.html) to read the file.
 
-We create a new file ``read-local-file.ts``:
-
-````ts title="read-local-file.ts"
-export default class ReadLocalFile extends godot.Node {
-	_ready(): void {
-		const file = new godot.FileAccess();
-		file.open("res://resources/test.csv", godot.FileAccess.ModeFlags.READ);
-		let fileContent: string = "";
-		while (!file.eof_reached()) {
-			fileContent += `${file.get_line()}\n`;
-		}
-		console.log(fileContent);
-	}
-}
-````
+We create a new file ``read-local-file.(mjs|ts)``:
+
+=== "JavaScript"
+
+    ````ts title="read-local-file.mjs"
+    export default class ReadLocalFile extends godot.Node {
+        _ready() {
+            const file = new godot.FileAccess();
+            file.open("res://resources/test.csv", godot.FileAccess.ModeFlags.READ);
+            let fileContent = "";
+            while (!file.eof_reached()) {
+                fileContent += `${file.get_line()}\n`;
+            }
+            console.log(fileContent);
+        }
+    }
+    ````
+=== "TypeScript"
+
+    ````ts title="read-local-file.ts"
+    export default class ReadLocalFile extends godot.Node {
+        _ready(): void {
+            const file = new godot.FileAccess();
+            file.open("res://resources/test.csv", godot.FileAccess.ModeFlags.READ);
+            let fileContent: string = "";
+            while (!file.eof_reached()) {
+                fileContent += `${file.get_line()}\n`;
+            }
+            console.log(fileContent);
+        }
+    }
+    ````
 

docs/examples/use-gdscript-in-js-or-ts.md

@@ -0,0 +1,68 @@
+# Use GDScript in TypeScript
+
+This example shows how to use a class written in GDScript in another TS class.
+
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
+
+## 1. Create the GDScript file
+
+First we create a simple class with GDScript inside a new file `scripts/gd/GDTest.gd`:
+
+````gdscript title="GDTest.gd"
+extends Node
+
+func _ready():
+	pass
+
+func print_in_gd_test():
+	print("gd_test")
+
+````
+
+## 2. Create a declaration (*.d.ts) for GDScript (only TypeScript)
+
+For proper TypeScript support we need to add a ``gdtest.d.ts`` file:
+
+````ts title="gdtest.d.ts"
+declare module "res://scripts/gd/GDTest.gd" {
+  class GDTest {
+    call(func: "print_in_gd_test"): void;
+
+    static new() {
+      return this;
+    }
+  }
+  export = GDTest;
+}
+````
+
+## 3. Use the class inside your TS file
+
+In the end we need to call the ``GDTest.gd`` from another `(.mjs|.ts)` file, like `main.(mjs|ts)`:
+
+=== "JavaScript"
+    ````ts title="main.mjs"
+    import GDTest from "res://scripts/gd/GDTest.gd";
+    
+    export default class Main extends godot.Node {
+        _ready() {
+            const gdTest = GDTest.new();
+            gdTest.call("print_in_gd_test");
+        }
+    }
+    
+    ````
+=== "TypeScript"
+    ````ts title="main.ts"
+    import GDTest from "res://scripts/gd/GDTest.gd";
+    
+    export default class Main extends godot.Node {
+        _ready(): void {
+            const gdTest: GDTest = GDTest.new();
+            gdTest.call("print_in_gd_test");
+        }
+    }
+    
+    ````
+
+> **Note:** The important thing here is that you use `new()` to instantiate and `call` to execute the function

docs/examples/use-gdscript-in-ts.md

@@ -2,15 +2,15 @@
 
 1. Define your JavaScript class and inherit from a Godot class, then export it as the **default** entry:
 
-```
+```javascript title="my-sprite.mjs"
 // The default export entry is treated as an exported class to Godot
 export default class MySprite extends godot.Sprite {
 	// this is _init() in GDScript
 	constructor() {
 		super();
 	}
 
-	_reajavascript title="my-sprite.mjs"dy() {}
+	_ready() {}
 
 	_process(delta) {}
 }