Merge pull request #7 from FragileTech/docs

Update documentation

README.md

@@ -18,6 +18,22 @@ Install Hydraclick via pip:
 pip install hydraclick
 ```
 
+### Supported Python Versions
+
+Hydraclick supports the following Python versions:
+
+- Python 3.9
+- Python 3.10
+- Python 3.11
+- Python 3.12
+
+### Supported Operating Systems
+
+Hydraclick is compatible with the following operating systems:
+
+- Ubuntu (latest)
+- macOS (latest)
+
 ## Getting Started
 
 ### Basic Usage
@@ -28,7 +44,7 @@ Define your function and decorate it with `@hydra_command` to create a CLI comma
 from omegaconf import DictConfig
 from hydraclick import hydra_command
 
-@hydra_command(config_path="config", config_name="my_config")
+@hydra_command(config_path="config_folder", config_name="file_without_extension")
 def my_function(config: DictConfig):
     print(f"Running with config: {config.pretty()}")
 ```
@@ -58,7 +74,6 @@ if __name__ == "__main__":
     main()
 ```
 
-
 ## API Reference
 
 ### `hydra_command`
@@ -68,7 +83,6 @@ Decorator to create CLI commands.
 ```python
 import omegaconf
 
-
 def hydra_command(
         config_path: str | Path | None = None,
         config_name: str | None = "config",
@@ -90,10 +104,7 @@ Hydraclick provides several configuration options to customize your CLI:
 - `config_path`: Path to the configuration directory. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
 - `config_name`: Name of the configuration file. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
 - `version_base`: Base version of the configuration. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
-- `as_kwargs`: The mode in which to run the function. If `True`, the function is run with the 
-configuration as keyword arguments. In this case the configuration is converted to a dictionary 
-before passing it to the function. If `False`, pass the configuration as a single `OmegaConf.DictConfig` object. 
-Defaults to `False`.
+- `as_kwargs`: The mode in which to run the function. If `True`, the function is run with the configuration as keyword arguments. In this case, the configuration is converted to a dictionary before passing it to the function. If `False`, pass the configuration as a single `OmegaConf.DictConfig` object. Defaults to `False`.
 - `preprocess_config`: Function to preprocess the configuration. It takes a `DictConfig` object and returns a `DictConfig` object.
 - `print_config`: Whether to print the configuration before execution.
 - `resolve`: Whether to resolve the configuration.
@@ -116,10 +127,29 @@ pip install flogging
 
 If `flogging` is not available, Hydraclick will log a warning and disable structured logging.
 
+## Terminal Text Effects
+
+Hydraclick supports terminal text effects using the [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects/) library to enhance the user experience with animated and styled text outputs in the terminal.
+Install the library with:
+```bash
+pip install hydraclick[terminaltexteffects]
+```
+
+```bash
+pip install terminaltexteffects
+```
+
+## Installing all the extras
+
+To install all the extras, use the following command:
+
+```bash
+pip install hydraclick[all]
+```
+
 ## Shell Completion
 
-Hydraclick supports generating shell completion scripts. Use the `--shell-completion` option 
-to generate scripts for your preferred shell.
+Hydraclick supports generating shell completion scripts. Use the `--shell-completion` option to generate scripts for your preferred shell.
 
 ```bash
 cli_app command --shell-completion install=bash > my_script_completion.sh
@@ -150,5 +180,4 @@ If you encounter any issues or have questions, feel free to open an issue on the
 - [Hydra](https://hydra.cc/) for powerful configuration management.
 - [Click](https://click.palletsprojects.com/) for creating beautiful CLIs.
 - [Flogging](https://github.com/FragileTech/flogging) for structured logging.
-
-
+- [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects) for enhancing terminal help text output.

docs/source/index.md

@@ -3,8 +3,16 @@
 
 ```{toctree}
 ---
-maxdepth: 2
-caption: API Reference
+maxdepth: 0
+caption:
+---
+markdown/terminal_effects.md
+```
+
+```{toctree}
+---
+maxdepth: 0
+caption:
 ---
 autoapi/index.rst
 ```

docs/source/markdown/terminal_effects.md

@@ -0,0 +1,73 @@
+# Terminal Text Effects
+
+Hydraclick supports terminal text effects using the [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects/) library to enhance the user experience with animated and styled text outputs in the terminal.
+
+## Configuring Terminal Text Effects
+
+Terminal text effects can be customized by adjusting print speeds, return speeds, and gradient colors. To apply terminal effects in Hydraclick, you can use the `terminal_effect` parameter provided in the `hydra_command` decorator.
+
+Example of setting terminal effects:
+
+```python
+from hydraclick import hydra_command, set_terminal_effect, display_terminal_effect
+from terminaltexteffects.utils.graphics import Color
+
+# Configure the effect
+def config_effect(effect):
+    effect.effect_config.print_speed = 15
+    effect.effect_config.print_head_return_speed = 5
+    effect.effect_config.final_gradient_stops = (Color("00ffae"), Color("00D1FF"), Color("FFFFFF"))
+    return effect
+
+# Set the terminal effect globally
+set_terminal_effect(display_terminal_effect)
+
+@hydra_command(config_path="config", config_name="my_config", terminal_effect=display_terminal_effect)
+def my_function(config):
+    print(f"Running with config: {config.pretty()}")
+```
+
+In this example, the `set_terminal_effect` function applies the terminal effect to help messages and command execution, providing animated and styled output.
+
+## Disabling Terminal Effects
+
+To disable terminal effects globally, set the following environment variables:
+
+- `OMEGACLICK_NO_TERMINAL_EFFECTS`
+- `NO_TERMINAL_EFFECTS`
+
+Setting either of these to `true`, `1`, or `yes` will disable all terminal effects:
+
+```bash
+export OMEGACLICK_NO_TERMINAL_EFFECTS=true
+```
+
+Hydraclick detects these variables and disables the effects accordingly.
+
+## Example Usage
+
+Hydraclick's CLI help messages and commands can be displayed with terminal effects. The `display_terminal_effect` function shows a text-based animation:
+
+```python
+from hydraclick import display_terminal_effect
+
+display_terminal_effect("Hello, world!")
+```
+
+By passing `display_terminal_effect` into the `hydra_command` decorator as the `terminal_effect` parameter, the terminal effects are automatically applied to your CLI.
+
+## Using the `terminal_effect` Parameter in `hydra_command`
+
+The `hydra_command` decorator allows you to specify a terminal effect through the `terminal_effect` parameter. When provided, it ensures the help messages and CLI output are animated with the specified effect.
+
+Example of using `hydra_command` with terminal effects:
+
+```python
+from hydraclick import hydra_command, display_terminal_effect
+
+@hydra_command(config_path="config", config_name="app_config", terminal_effect=display_terminal_effect)
+def my_function(config):
+    print(f"Running with config: {config.pretty()}")
+```
+
+This integrates terminal effects seamlessly into your CLI, adding visual appeal and dynamic text output.

pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
 ]
 [project.optional-dependencies]
 flogging = ["flogging>=0.0.22"]
-terminal-effects = ["terminaltexteffects>=0.11.0"]
+terminaltexteffects = ["terminaltexteffects>=0.11.0"]
 all = ["flogging>=0.0.22", "terminaltexteffects>=0.11.0"]
 test = [
     "psutil>=5.8.0",