Initial commit

2025-04-09 09:34:15 +02:00
commit c19fb93ec5
47 changed files with 5174 additions and 0 deletions
@@ -0,0 +1,150 @@
+# Edison Themes Guide
+
+Edison supports rich syntax highlighting for commands through its theme system. This guide explains how to use and customize themes in Edison.
+
+## Available Themes
+
+Edison uses the Rich library's syntax highlighting capabilities, which are powered by Pygments. The following themes are available out of the box:
+
+| Theme Name | Description | Style |
+|------------|-------------|-------|
+| monokai | Default theme with vibrant colors | Dark |
+| github-dark | Based on GitHub's dark theme | Dark |
+| solarized-dark | Popular dark theme with softer colors | Dark |
+| dracula | High contrast dark theme | Dark |
+| nord | Bluish dark theme | Dark |
+| gruvbox-dark | Retro dark theme with warm colors | Dark |
+| one-dark | Based on Atom's One Dark theme | Dark |
+| vs | Based on Visual Studio's default theme | Light |
+| solarized-light | Light version of the Solarized theme | Light |
+| gruvbox-light | Light version of the Gruvbox theme | Light |
+
+## Using Themes
+
+You can specify a theme in three ways:
+
+### 1. In the Configuration File
+
+Edit your `edison.yaml` file to set the default theme:
+
+```yaml
+ui:
+  theme: "github-dark"  # Change from the default "monokai"
+```
+
+### 2. Via Command-Line Argument
+
+Specify a theme for a single command:
+
+```bash
+edison --theme dracula "list all files"
+```
+
+### 3. In Interactive Mode
+
+The theme specified in the configuration or command-line will be used in interactive mode as well.
+
+## Theme Elements
+
+Themes apply different colors to various syntax elements:
+
+- **Keywords**: Shell keywords like `if`, `for`, `while`, etc.
+- **Strings**: Text enclosed in quotes
+- **Comments**: Lines starting with `#` in bash
+- **Variables**: Names prefixed with `$` in bash
+- **Operators**: Symbols like `=`, `-gt`, `|`, etc.
+- **Functions**: Function names and calls
+- **Numbers**: Numeric literals
+- **Punctuation**: Brackets, parentheses, etc.
+
+## Creating Custom Themes
+
+While Edison doesn't directly support custom themes, you can create your own by extending the Rich library:
+
+1. Create a custom theme file (e.g., `custom_themes.py`):
+
+```python
+from pygments.style import Style
+from pygments.token import (
+    Comment, Error, Keyword, Literal, Name, Number, Operator, String, Text
+)
+
+class CustomTheme(Style):
+    """A custom syntax highlighting theme."""
+    
+    # Define colors
+    background_color = "#282c34"
+    highlight_color = "#3e4451"
+    
+    # Define token colors
+    styles = {
+        Text: "#abb2bf",
+        Error: "#e06c75",
+        Comment: "#5c6370",
+        Keyword: "#c678dd",
+        Keyword.Reserved: "#c678dd",
+        Keyword.Namespace: "#c678dd",
+        Name: "#abb2bf",
+        Name.Builtin: "#e5c07b",
+        Name.Function: "#61afef",
+        Name.Class: "#e5c07b",
+        Name.Decorator: "#61afef",
+        Name.Variable: "#e06c75",
+        Number: "#d19a66",
+        Operator: "#56b6c2",
+        String: "#98c379",
+    }
+```
+
+2. Register your theme with Pygments:
+
+```python
+from pygments.styles import STYLE_MAP
+STYLE_MAP["custom"] = "custom_themes.CustomTheme"
+```
+
+3. Use your custom theme:
+
+```python
+from edison.utils.markdown_utils import print_command_rich
+print_command_rich("ls -la", theme="custom")
+```
+
+## Theme Compatibility
+
+Theme appearance may vary depending on:
+
+1. **Terminal Capabilities**: Some terminals have limited color support or override colors with their own theme settings.
+
+2. **Color Schemes**: Your terminal's color scheme may affect how themes appear.
+
+3. **Font Settings**: Certain font features like ligatures can affect the display of syntax-highlighted code.
+
+## Troubleshooting
+
+If you're not seeing theme differences:
+
+1. **Check Terminal Support**: Ensure your terminal supports 256 colors or true color:
+   ```bash
+   echo $TERM
+   echo $COLORTERM
+   ```
+   
+   For best results, use a terminal that supports true color (24-bit color).
+
+2. **Try High-Contrast Themes**: If differences are subtle, try themes with higher contrast like `dracula` vs `solarized-light`.
+
+3. **Use Complex Commands**: Simple commands might not have enough syntax elements to show significant differences between themes.
+
+## Demo Scripts
+
+Edison includes two demonstration scripts to help you visualize theme differences:
+
+1. `theme_demo.py`: Shows the same bash script rendered with different themes
+2. `edison_theme_demo.py`: Demonstrates how Edison's theme functionality works with its markdown_utils module
+
+Run these scripts to see the themes in action:
+
+```bash
+python theme_demo.py
+python edison_theme_demo.py