docs: document registry and setup auto push for docs (#159)

* docs(ecs): document ecs and design choices

* docs(ecs): setup sphinx for ecs documentation

* docs(ecs): start connecting typescript to sphinx

* docs(ecs): finish cpp side of documentation

* docs: setup new doc system

* docs(actions): setup push-docs actions to synchronize documentation

* docs: setup auto push of generated documentation for ecs

* docs(usage): replace template with cli mention and delete template example

* ci: update push-docs workflow to monitor specific documentation paths

---------

Co-authored-by: Exelo <exelo.corp@gmail.com>

Author: MartinFillon

.github/workflows/push-docs.yml

@@ -0,0 +1,49 @@
+name: synchronize-docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "packages/ecs-lib/docs/**"
+      - "packages/ecs-lib/wasm/**"
+  workflow_dispatch:
+
+jobs:
+  synchronize:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout engine
+        uses: actions/checkout@v5
+        with:
+          path: engine
+
+      - name: Checkout docs
+        uses: actions/checkout@v5
+        with:
+          path: docs
+          repository: nanoforge-dev/docs
+          token: ${{ secrets.ACTIONS_KEY }}
+
+      - name: setup git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "username@users.noreply.github.com"
+
+      - name: setup registry code documentation
+        run: |
+          apt install doxygen -y
+          cd engine/packages/ecs-lib/docs
+          doxygen Doxyfile
+          cd -
+          cp engine/packages/ecs-lib/docs engine/docs/registry/api
+
+      - name: synchronize docs
+        run: |
+          mkdir -p docs/engine
+          cp engine/docs/. -r docs/engine
+          cd docs
+          git add .
+          git commit -m "chore(engine): updating docs"
+          git push origin main

README.md

@@ -1,3 +1,5 @@
+[![Nanoforge Documentation](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml/badge.svg)](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml)
+
 # Engine
 
 This repository contains the full engine for NanoForge.
@@ -20,6 +22,10 @@ This is the full nanoforge engine including all the default libraries.
 
 In order to manage this project we use (pnpm)[https://pnpm.io/]
 
+## Documentation
+
+The full documentation can be found at: [https://nanoforge-dev.github.io/docs/engine](https://nanoforge-dev.github.io/docs/engine)
+
 ## Installing dependencies
 
 To install dependencies run:

docs/.gitignore

@@ -0,0 +1 @@
+Doxyfile

docs/Introduction.md

@@ -0,0 +1,7 @@
+Documentation
+=============
+
+The documentation for the engine is seperated between the different libraries of the engine.
+Then everything is packed up and put into this site. The documentation is handled on the engine repository and then automatically pushed.
+
+This documentation is written in restructured text in order for it to be easier to operate with. We use sphinx to generate the relevant generated documentation.

docs/documentation.rst

@@ -0,0 +1,20 @@
+Introduction to using the Engine
+================================
+
+Whether you work on this engine as a devlopper or you wanna use this
+engine you gonna want to have a test project. This is a walkthrough on
+how to setup a basic project
+
+As a devlopper on the engine
+----------------------------
+
+As a devlopper you want to be able to use your changes in your project.
+Therefore it is recommended to use the provided `cli <https://github.com/NanoForge-dev/CLI>`__
+
+As a user
+---------
+
+As a user you can either use the template and change the dependencies
+location. Or you can create a project and add the nanoforge
+dependencies. Note that it is recommended to use bun as a package
+manager.

docs/how_to_use.rst

@@ -0,0 +1,12 @@
+Engine
+======
+
+.. toctree::
+    :maxdepth: 2
+
+    registry
+    documentation.rst
+    how_to_use.rst
+
+In this doc you will find both the how to use and why use this engine as well as its library.
+To understand how to use this engine please refer to :doc:`/how_to_use`

docs/index.rst

@@ -0,0 +1,44 @@
+Registry
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    writing_web_assembly.rst
+
+The registry class is written in C++ and exposed to WebAssembly using
+Emscripten. This choice was made to leverage the performance benefits of
+C++ for managing entities and components in an ECS architecture.
+Emscripten allows us to compile C++ code into WebAssembly, which can
+then be used in web applications, providing a bridge between
+high-performance C++ code and JavaScript.
+
+Design Choices
+--------------
+
+This design makes some trade-offs between performance and ease of use. A
+pure C++ ECS would have been easier to use but having to bind it as us
+make choices that impact usability.
+
+Const Correctness
+~~~~~~~~~~~~~~~~~
+
+In a regular C++ ECS, const correctness is a given, but when exposing
+C++ to WebAssembly, as in C++ we can force constant of return values.
+But in WebAssembly, the concept of const correctness does not directly
+translate to JavaScript. Therefore, methods that would typically return
+const references in C++ may return non-const references or copies when
+exposed to WebAssembly. We deciced to keep the const correctness in the
+C++ code to maintain clarity and intent within the C++ domain, even if
+it doesn't fully carry over to the WebAssembly interface.
+
+Error Handling
+~~~~~~~~~~~~~~
+
+Any thrown exceptions in C++ will result in a runtime error in
+JavaScript. The problem with this approach is that the error messages
+may not be as descriptive or user-friendly as native JavaScript errors.
+As every error thrown in C++ will be caught as a generic runtime error
+in JavaScript, it can make debugging more challenging. To mitigate this,
+we recommend thorough testing and validation within the C++ code to
+catch potential issues before they propagate to the WebAssembly layer.

docs/registry/index.rst

@@ -0,0 +1,35 @@
+Writing Web Assembly
+====================
+
+Code Splitting
+--------------
+
+When writing Web Assembly modules, it's important to consider code
+splitting for readability and maintainability. We try to split binding
+and code logic into separate files where possible. This helps keep the
+codebase organized and makes it easier to navigate.
+
+For example, in the ECS package, the binding logic is in ``.cpp`` files,
+while the core logic resides in ``.hpp`` files. This separation allows
+developers to focus on either the binding or the logic without being
+overwhelmed by both at the same time.
+
+Documentation
+-------------
+
+When documenting Web Assembly modules, we follow a similar approach to
+C++ documentation. We use Doxygen-style comments to provide clear and
+concise explanations of classes, methods, and parameters. This
+documentation is crucial for developers who will be using or maintaining
+the Web Assembly modules, as it provides necessary context and usage
+information.
+
+Logging
+-------
+
+Logging in Web Assembly is costly memory-wise due to the interaction
+between C++ and JavaScript. Therefore, we recommend to log from the
+JavaScript side whenever possible. If logging from C++ is necessary, be
+aware of the potential performance implications and memory leaks. Web
+assembly vm is memory limited, so excessive logging will lead to
+out-of-memory errors.