docs creation

Author: raidos23

docs/how_to_create_a_bc_plugin.md

@@ -0,0 +1,82 @@
+**Overview**
+BC plugins (BCASL) run before compilation. They are Python packages placed in `Plugins/`, discovered automatically, and executed through the `on_pre_compile` hook.
+
+**Steps**
+1. Create a package folder in `Plugins/<plugin_name>/` with an `__init__.py`.
+2. Implement a subclass of `BcPluginBase` and decorate it with `@bc_register`.
+3. Define a `PluginMeta` with a unique `id`.
+4. Configure the plugin in `bcasl.yml` (optional but recommended for ordering and enable/disable).
+
+**Minimal Plugin**
+```python
+from __future__ import annotations
+
+from bcasl import bc_register
+from Plugins_SDK.BcPluginContext import BcPluginBase, PluginMeta, PreCompileContext
+from Plugins_SDK.GeneralContext import Dialog
+
+log = Dialog()
+
+META = PluginMeta(
+    id="example.clean",
+    name="Example Clean",
+    version="0.1.0",
+    description="Remove .pyc files before build",
+    author="You",
+    tags=("clean",),
+    required_bcasl_version="2.0.0",
+    required_core_version="1.0.0",
+    required_plugins_sdk_version="1.0.0",
+    required_bc_plugin_context_version="1.0.0",
+    required_general_context_version="1.0.0",
+)
+
+
+@bc_register
+class ExampleClean(BcPluginBase):
+    meta = META
+
+    def __init__(self):
+        super().__init__(META)
+
+    def on_pre_compile(self, ctx: PreCompileContext) -> None:
+        if not ctx.is_workspace_valid():
+            log.log_warn("Workspace not valid or bcasl.yml missing")
+            return
+        for pyc in ctx.iter_files(["**/*.pyc"], ctx.get_exclude_patterns()):
+            try:
+                pyc.unlink()
+            except Exception as exc:
+                log.log_warn(f"Failed to remove {pyc}: {exc}")
+```
+
+**Configuration**
+BCASL reads `bcasl.yml` or `.bcasl.yml` in the workspace root. Only the `.yml` extension is supported.
+```yaml
+required_files:
+- main.py
+file_patterns:
+- "**/*.py"
+exclude_patterns:
+- "**/__pycache__/**"
+- "**/*.pyc"
+options:
+  enabled: true
+  sandbox: true
+  plugin_timeout_s: 5
+  plugin_parallelism: 0
+  iter_files_cache: true
+plugins:
+  example.clean:
+    enabled: true
+    priority: 10
+plugin_order:
+- example.clean
+```
+
+**Notes**
+- Plugin ids come from `PluginMeta.id`, and configuration uses those ids.
+- Plugins can also register via a legacy `bcasl_register(manager)` function, but `@bc_register` is preferred.
+- Use `Plugins_SDK.GeneralContext.Dialog` for UI interactions and logging. Direct Qt dialogs are blocked in sandboxed runs.
+- Timeouts can be controlled with `options.plugin_timeout_s` or the env var `PYCOMPILER_BCASL_PLUGIN_TIMEOUT`.
+- Parallelism can be controlled with `options.plugin_parallelism` or the env var `PYCOMPILER_BCASL_PARALLELISM`.

docs/how_to_create_an_engine.md

@@ -0,0 +1,52 @@
+**Overview**
+PyCompiler_ARK engines are Python packages loaded from `ENGINES/` at startup. Each engine registers itself with `@engine_register` and provides a `CompilerEngine` subclass that builds the command used to compile a file.
+
+**Steps**
+1. Create a package folder in `ENGINES/<engine_id>/` with an `__init__.py`.
+2. Implement a subclass of `CompilerEngine` in that `__init__.py`.
+3. Decorate the class with `@engine_register` and set the required attributes.
+4. Restart the app so the loader auto-discovers the package.
+
+**Minimal Example**
+```python
+from __future__ import annotations
+
+import sys
+from engine_sdk import CompilerEngine, engine_register
+
+
+@engine_register
+class MyEngine(CompilerEngine):
+    id = "my_engine"
+    name = "My Engine"
+    version = "0.1.0"
+    required_core_version = "1.0.0"
+    required_sdk_version = "1.0.0"
+
+    @property
+    def required_tools(self):
+        return {"python": ["mytool"], "system": []}
+
+    def build_command(self, gui, file):
+        return [sys.executable, "-m", "mytool", file]
+```
+
+**Required API**
+- `id`: Unique engine id (string).
+- `name`: Display name.
+- `version`: Engine version.
+- `required_core_version` and `required_sdk_version`: Compatibility info.
+- `build_command(self, gui, file) -> list[str]`: Full command list with the program at index 0.
+
+**Optional API**
+- `preflight(self, gui, file) -> bool`: Return False to abort.
+- `program_and_args(self, gui, file)`: Override if you need custom program/args separation.
+- `environment(self) -> dict[str, str] | None`: Inject environment variables.
+- `on_success(self, gui, file)`: Post-build hook.
+- `required_tools` property: Python and system tools that should be installed.
+- `create_tab(self, gui)`: Provide a custom settings tab for your engine.
+- `apply_i18n(self, gui, tr)`: Update text when language changes. Provide `languages/<code>.json` in your engine package if you want translations.
+
+**Notes**
+- The loader only imports packages under `ENGINES/` that contain `__init__.py`. Plain `.py` files are ignored.
+- Keep engines stateless. GUI state is passed in `gui`.