docs(io.output): 📝 add some note about output formatters

Author: kikkomep

docs/3_usage_api.rst

@@ -57,7 +57,77 @@ representing the metadata and validates it against a given validation profile.
         rocrate_metadata = json.load(f)
         
         # validate the metadata dictionary
-        result = validation_report = validate_metadata_as_dict(rocrate_metadata, settings=settings)
+        result = validate_metadata_as_dict(rocrate_metadata, settings=settings)
 
         # process the validation result as needed
         ...
+
+
+Formatting Validation Results
+-----------------------------
+
+Validation results can be rendered using different output formatters provided by
+the library. Two formatter types are available: *text* and *JSON*.  
+Both rely on the ``rich`` Python library and integrate with the
+``rocrate_validator.io.output.console.Console`` class, which extends
+``rich.console.Console`` to support custom formatter registration.
+
+To format results, create a ``Console`` instance, register one formatter,
+and then print any validation output object (e.g., the full report or the
+aggregated statistics).
+
+
+TextOutputFormatter
+~~~~~~~~~~~~~~~~~~~
+
+``TextOutputFormatter`` renders validation reports as human-readable, styled text.  
+It is typically used for console output, report generation, or writing results
+to a file.
+
+.. code-block:: python
+
+    from rocrate_validator.io.output.console import Console
+    from rocrate_validator.io.output.text import TextOutputFormatter
+
+    console = Console()
+    console.register_formatter(TextOutputFormatter())
+
+    # Print the main validation result
+    console.print(result)
+
+    # Print aggregated statistics (violations by severity, executed checks, etc.)
+    console.print(result.statistics)
+
+    # Write the output to a file
+    with open("validation_report.txt", "w") as f:
+        file_console = Console(file=f)
+        file_console.register_formatter(TextOutputFormatter())
+        file_console.print(result.statistics)
+        file_console.print(result)
+
+
+JSONOutputFormatter
+~~~~~~~~~~~~~~~~~~~
+
+``JSONOutputFormatter`` produces JSON-structured output, suitable for logging,
+programmatic processing, or integration with external tools.
+
+.. code-block:: python
+
+    from rocrate_validator.io.output.console import Console
+    from rocrate_validator.io.output.json import JSONOutputFormatter
+
+    console = Console()
+    console.register_formatter(JSONOutputFormatter())
+
+    # Print the main validation result as JSON
+    console.print(result)
+
+    # Print the aggregated statistics
+    console.print(result.statistics)
+
+    # Write the output to a file
+    with open("validation_report.json", "w") as f:
+        file_console = Console(file=f)
+        file_console.register_formatter(JSONOutputFormatter())
+        file_console.print(result)