Add MkDocs Material documentation site with per-platform webhook guides and GitHub Pages deployment

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install MkDocs and Material theme
+        run: pip install "mkdocs-material" "mkdocs<2"
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/api.md

@@ -0,0 +1,115 @@
+# Python API Reference
+
+`whecho` exposes a small public Python API that lets you send webhook notifications directly from your scripts without using the command line.
+
+---
+
+## `whecho_simple`
+
+```python
+from whecho.whecho import whecho_simple
+```
+
+Sends a message to a webhook URL using the simple format.
+
+### Signature
+
+```python
+def whecho_simple(msg: str, url: str = "", debug: bool = False) -> Optional[requests.models.Response]
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `msg` | `str` | *(required)* | The message text to send. |
+| `url` | `str` | `""` | The webhook URL to post to. If empty or omitted, the URL saved via `whecho --init` is used. |
+| `debug` | `bool` | `False` | When `True`, prints request details and returns the `Response` object. |
+
+### Returns
+
+- `None` by default.
+- `requests.models.Response` when `debug=True`.
+
+### Raises
+
+- `ValueError` — if no URL is provided and no default URL is configured.
+- `ValueError` — if `msg` is empty.
+
+### Examples
+
+**Basic usage (uses saved default URL):**
+
+```python
+from whecho.whecho import whecho_simple
+
+whecho_simple("Training complete! ✅")
+```
+
+**With a specific URL:**
+
+```python
+from whecho.whecho import whecho_simple
+
+whecho_simple("Deployment done!", url="https://discord.com/api/webhooks/...")
+```
+
+**Debug mode (returns the HTTP response):**
+
+```python
+from whecho.whecho import whecho_simple
+
+response = whecho_simple("Hello!", debug=True)
+print(response.status_code)
+```
+
+**Notify when a long task finishes:**
+
+```python
+from whecho.whecho import whecho_simple
+import time
+
+def train_model():
+    time.sleep(60)  # simulate long task
+
+train_model()
+whecho_simple("Model training complete! 🎉")
+```
+
+---
+
+## Platform Auto-Detection
+
+`whecho_simple` automatically detects the target platform from the URL and formats the JSON payload accordingly:
+
+| URL contains | Platform | Payload format |
+|---|---|---|
+| `discord.com` or `discordapp.com` | Discord | `{"username": "user@machine", "content": "..."}` |
+| `slack.com` | Slack | `{"text": "..."}` |
+| `webhook.office.com` | Microsoft Teams | `{"text": "..."}` |
+| `webexapis.com` | Webex | `{"markdown": "..."}` |
+| *(anything else)* | Generic | `{"text": "..."}` |
+
+This means `whecho_simple` works out of the box with all supported platforms — no extra configuration needed beyond the URL.
+
+---
+
+## Configuration
+
+The configuration (including the default webhook URL) is stored in a platform-specific location:
+
+| OS | Config path |
+|---|---|
+| Linux | `~/.config/.whecho/config.toml` |
+| macOS | `~/Library/Application Support/.whecho/config.toml` |
+| Windows | `%APPDATA%\.whecho\config.toml` |
+
+Run `whecho --init` to set or update the configuration interactively.
+
+### Config fields
+
+| Field | Description |
+|---|---|
+| `default_url` | The default webhook URL used when no URL is passed. |
+| `user` | Your username (auto-detected, used in Discord messages). |
+| `machine` | Your machine hostname (auto-detected, used in Discord messages). |

docs/index.md

@@ -0,0 +1,135 @@
+# whecho
+
+**Linux echo with webhooks! ⚓**
+
+Don't guess when a job is finished — have it message you! `whecho` is a command-line tool (and Python library) that sends notifications to messaging platforms like Discord, Slack, Webex, and Microsoft Teams via webhooks, so you know the moment a long-running task completes.
+
+---
+
+## Installation
+
+```bash
+pip install whecho
+```
+
+**Requirements:** Python 3.6+
+
+---
+
+## Quickstart
+
+### 1. Obtain a Webhook URL
+
+First, generate a webhook URL from your preferred messaging platform:
+
+| Platform | Guide |
+|---|---|
+| Discord | [Discord Webhook Setup](platforms/discord.md) |
+| Slack | [Slack Webhook Setup](platforms/slack.md) |
+| Webex | [Webex Webhook Setup](platforms/webex.md) |
+| Microsoft Teams | [Teams Webhook Setup](platforms/teams.md) |
+
+### 2. Initialize whecho
+
+Run the interactive setup to save your webhook URL:
+
+```bash
+$ whecho --init
+Current config:
+[1] default_url: None
+[2] user: myuser
+[3] machine: my-machine
+
+Please enter the number/name of the config option you would like to modify (empty or Q to exit): 1
+Please enter the new value for default_url: https://your-webhook-url-here
+Successfully modified default_url to https://your-webhook-url-here!
+...
+Please enter the number/name of the config option you would like to modify (empty or Q to exit): q
+Successfully initialized whecho!
+```
+
+### 3. Send a Message
+
+```bash
+$ whecho "Hello from the terminal!"
+```
+
+That's it! Your message will appear in your configured messaging platform immediately.
+
+---
+
+## Usage
+
+### Command-Line
+
+```bash
+# Send a message using your saved default webhook
+$ whecho "Build complete!"
+
+# Send to a specific webhook URL (no init required)
+$ whecho -u https://your-webhook-url "Deployment finished!"
+
+# Use the --msg flag instead of a positional argument
+$ whecho --msg "Training complete!"
+
+# Append whecho to any command to be notified when it finishes
+$ sleep 60 && whecho "Sleep done!"
+```
+
+### Python API
+
+```python
+from whecho.whecho import whecho_simple
+
+# Use the saved default URL
+whecho_simple("I'm inside Python 🐍")
+
+# Use a specific webhook URL
+whecho_simple("Custom URL message", url="https://your-webhook-url")
+```
+
+See the [Python API reference](api.md) for full details.
+
+---
+
+## CLI Reference
+
+```
+usage: whecho [-h] [--version] [-m MSG] [--init] [-u URL] [-d] [MSG ...]
+
+Linux echo with webhooks! ⚓
+
+positional arguments:
+  MSG                The message to echo.
+
+optional arguments:
+  -h, --help         show this help message and exit
+  --version          Prints the version of whecho and exits.
+  -m MSG, --msg MSG  The message to echo (same as 1st positional argument).
+  --init             Initializes whecho. Also used to change current config.
+  -u URL, --url URL  The webhook URL to send the message to.
+  -d, --debug        Whether to print debugging information.
+```
+
+---
+
+## Supported Platforms
+
+whecho automatically detects the target platform from the webhook URL and formats the message accordingly:
+
+- **[Discord](platforms/discord.md)** — sends as a bot message with username set to `user@machine`
+- **[Slack](platforms/slack.md)** — sends using Slack's incoming webhook text format
+- **[Webex](platforms/webex.md)** — sends with Markdown support
+- **[Microsoft Teams](platforms/teams.md)** — sends via Office 365 connector webhooks
+- **Generic webhooks** — sends a JSON body with a `text` field
+
+---
+
+## Table of Contents
+
+- [Python API](api.md)
+- Messaging Platform Guides
+    - [Discord](platforms/discord.md)
+    - [Slack](platforms/slack.md)
+    - [Webex](platforms/webex.md)
+    - [Microsoft Teams](platforms/teams.md)