docs: update docstring format and generator documentation for clarity

Author: gitmobkab

docs/dev/docstrings.md

@@ -47,7 +47,7 @@ Locale dependent:
 
 If omitted, the generator is assumed to be locale-independent.
 
-!!! note title="Not entirely strict"
+!!! note "Not entirely strict"
     To be honest, if the line below Locale dependent is not exactly `yes` it's treated as `no`. But it's best to follow the format strictly to avoid confusion.
 
 ### `Args`

docs/dev/generators_registry.md

@@ -42,7 +42,7 @@ Generators must not use `**kwargs`. The DSL only supports positional and named a
 def my_gen(**kwargs) -> str: ...
 ```
 
-### `*args` and named parameters are mutually exclusive
+### `*args` and POSITIONAL_OR_KEYWORD parameters are mutually exclusive
 
 A generator may use either `*args` (var positional) or POSITIONAL_OR_KEYWORD parameters — but not both simultaneously.
 
@@ -60,8 +60,9 @@ def yet_another_gen(*args, extra: str = "") -> str: ...
 # Invalid — POSITIONAL_OR_KEYWORD params with *args (var positional)
 def invalid_gen(extra: str, *args) -> str: ...
 
-# WHY ? Because the Semantic Validator for the DSL cannot currently handle this combination. It would require a more complex parsing logic to determine which arguments are meant for `*args` and which are actual positionals parameters, especially since the user can pass any number of values for `*args`. To keep things simple and unambiguous, we enforce this constraint.
 ```
+WHY ? Because the Semantic Validator for the DSL cannot currently handle this combination. It would require a more complex parsing logic to determine which arguments are meant for `*args` and which are actual positionals parameters, especially since the user can pass any number of values for `*args`. To keep things simple and unambiguous, we enforce this constraint.
+
 
 !!! note "About union types"
     The current implementation of the docstring parser and the semantic validator does not support union types (e.g., `str | int`) in generator signatures. This will be updated in future updates. and no, even Any is not supported too.
@@ -72,12 +73,12 @@ def invalid_gen(extra: str, *args) -> str: ...
 
 To add a new generator, simply define a function in any non-private module under `copia.generators` and ensure it follows the constraints outlined above. The function will be automatically registered and available for use in the DSL.
 
-first check if the module you want to add the generator to already exists. If it does, add your function there. If not, create a new module and add your function there.
+- first check if the module you want to add the generator to already exists. If it does, add your function there. If not, create a new module and add your function there.
 
-since the registry is built dynamically, you don't need to do anything else to make your generator available — just define it and it will be picked up when the module is imported.
+- since the registry is built dynamically, you don't need to do anything else to make your generator available — just define it and it will be picked up when the module is imported.
 
-to ensure your generator is properly documented, follow the docstring format outlined in the [docstrings guide](./docstrings.md). This will help users understand how to use your generator and what it does.
+- to ensure your generator is properly documented, follow the docstring format outlined in the [docstrings guide](./docstrings.md). This will help users understand how to use your generator and what it does.
 
-and to finish, simply run pytest tests/test_generators_discover.py to avoid any import warnings or errors related to your new generator. If you see an ImportWarning about overriding a generator, it means you have a naming conflict — either rename your generator or remove the conflicting one. If you see an error about `**kwargs` or invalid parameter combinations, adjust your function signature accordingly.
+- and to finish, simply run pytest tests/test_generators_discover.py to avoid any import warnings or errors related to your new generator. If you see an ImportWarning about overriding a generator, it means you have a naming conflict — either rename your generator or remove the conflicting one. If you see an error about `**kwargs` or invalid parameter combinations, adjust your function signature accordingly.
 
 > just keep in mind, the function signature is a direct interface to users, so keep it simple and intuitive. Avoid complex parameter combinations that could confuse users or make the generator difficult to use in the DSL. The goal is to provide a clear and straightforward way for users to generate data without having to worry about the underlying implementation details.

docs/dev/index.md

@@ -10,4 +10,4 @@ This section documents the internals of Copia for contributors and developers wh
 - [Docstring format](docstrings.md) — the docstring convention Copia uses to generate documentation
 - [The dynamic generators system](generators_registry.md) — how generators are registered and what constraints apply
 - [The semantic validator](validator.md) — how Copia validates DSL calls against generator signatures
-- [How `ref` works](ref.md) — the internals of the `ref()` generator
+- [How `fetch` works](fetch.md) — the internals of the `fetch()` generator

docs/installation.md

@@ -28,10 +28,12 @@ Copia requires **Python 3.13 or higher**.
 
 === "From source"
 
+    we recommend [uv](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) to download the repo from source
+
     ```bash
     git clone https://github.com/gitmobkab/copia
     cd copia
-    pip install -e .
+    uv sync --all-groups
     ```
 
 ---

mkdocs.yml

@@ -26,6 +26,7 @@ theme:
     - content.code.annotate
     - navigation.tabs
     - navigation.tabs.sticky
+    - content.tooltips
 
 hooks:
   - hooks/dsl_hook.py