Merge pull request #74 from IBM/docs-clean

Add performance testing and documentation authoring guide to docs

Author: crivetimihai

docs/docs/development/.pages

@@ -2,4 +2,5 @@ nav:
   - index.md
   - github.md
   - building.md
+  - documentation.md
   - packaging.md

docs/docs/development/documentation.md

@@ -0,0 +1,156 @@
+# Writing & Publishing Documentation
+
+Follow this guide when you need to add or update markdown pages under `docs/` and preview the documentation locally.
+
+---
+
+## 🧩 Prerequisites
+
+* **Python ≥ 3.10** (only for the initial virtual env – *not* required if you already have one)
+* `make` (GNU Make 4+)
+* (First-time only) **[`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/)** and plugins are installed automatically by the *docs* `Makefile`.
+* One-time GitHub setup, e.g. [gitconfig setup](./github.md#16-personal-git-configuration-recommended)
+
+---
+
+## ⚡ One-liner for a live preview
+
+```bash
+cd docs
+make venv     # First-time only, installs dependencies into a venv under `~/.venv/mcpgateway-docs`
+make serve    # http://localhost:8000 (auto-reload on save)
+```
+
+*The `serve` target automatically creates a project-local virtual environment (under `~/.venv/mcpgateway-docs`) the first time you run it and installs all doc dependencies before starting **MkDocs** in live-reload mode.*
+
+---
+
+## 📂 Folder layout
+
+```text
+repo-root/
+├─ docs/              # MkDocs project (DO NOT put .md files here!)
+│  ├─ docs/           # <-- ────────────▶  place Markdown pages here
+│  │  └─ ...
+│  ├─ mkdocs.yml      # MkDocs config & navigation
+│  └─ Makefile        # build / serve / clean targets
+└─ Makefile           # repo-wide helper targets (lint, spellcheck, …)
+```
+
+* **Add new pages** inside `docs/docs/` – organise them in folders that make sense for navigation.
+* **Update navigation**: edit `.pages` for your section so your page shows up in the left-hand nav.
+
+> **Tip:** MkDocs Material auto-generates "Edit this page" links – keep file names lowercase-hyphen-case.
+
+---
+
+## ✏️ Editing tips
+
+1. Write in **standard Markdown**; we also support admonitions, call-outs, and Mermaid diagrams.
+2. Use relative links between pages: `[Gateway API](../api/index.md)`.
+3. For local images place them under `docs/docs/images/` and reference with `![](../images/example.png)`.
+4. Never edit `mkdocs.yml` - all nav structure is defined in `.pages` files (one per directory).
+
+---
+
+## ✏️ Writing docs
+
+Start each new Markdown file with a clear **`# Heading 1`** title – this becomes the visible page title and is required for proper rendering in MkDocs.
+
+Follow the conventions and layout guidelines from the official **[MkDocs Material reference](https://squidfunk.github.io/mkdocs-material/reference/)** for callouts, tables, code blocks, and more. This ensures consistent formatting across the docs.
+
+Keep file names in `lowercase-hyphen-case.md` and use relative links when referencing other docs or images.
+
+---
+
+## 🗂️ Ordering pages with `.pages`
+
+For directories that contain multiple Markdown files, we rely on the [awesome-pages](https://henrywhitaker3.github.io/mkdocs-material-dark-theme/plugins/awesome-pages/) MkDocs plugin.
+
+Creating a `.pages` file inside a folder lets you:
+
+* **Set the section title** (different from the folder name).
+* **Control the left‑nav order** without touching the root `mkdocs.yml`.
+* **Hide** specific files from the navigation.
+
+We do **not** auto-generate the `nav:` structure – you must create `.pages` manually.
+
+Example – *docs for the **development** section:*
+
+```yaml
+# docs/docs/development/.pages
+# This file affects ONLY this folder and its sub‑folders
+
+# Optional: override the title shown in the nav
+# title: Development Guide
+
+nav:
+  - index.md        # ➟ /development/ (landing page)
+  - github.md       # contribution workflow
+  - building.md     # local build guide
+  - packaging.md    # release packaging steps
+```
+
+Guidelines:
+
+1. Always include `index.md` first so the folder has a clean landing URL.
+2. List files **in the exact order** you want them to appear; anything omitted is still built but won't show in the nav.
+3. You can nest `.pages` files in deeper folders – rules apply hierarchically.
+4. Avoid circular references: do **not** include files from *other* directories.
+
+After saving a `.pages` file, simply refresh the browser running `make serve`; MkDocs will hot‑reload and the navigation tree will update instantly.
+
+---
+
+
+
+## ✅ Pre-commit checklist
+
+From the **repository root** run **all** lint & QA checks before pushing:
+
+```bash
+make spellcheck           # Spell-check the codebase
+make spellcheck-sort      # Sort local spellcheck dictionary
+make markdownlint         # Lint Markdown files with markdownlint (requires markdownlint-cli)
+make pre-commit           # Run all configured pre-commit hooks
+```
+
+> These targets are defined in the top-level `Makefile`. Make sure you're in the repository root when running these targets.
+
+---
+
+## 🧹 Cleaning up
+
+```bash
+cd docs
+make clean       # remove generated site/
+make git-clean   # remove ignored files per .gitignore
+make git-scrub   # blow away *all* untracked files – use with care!
+```
+
+---
+
+## 🔄 Rebuilding the static site
+
+> This is not necessary, as this will be done automatically when publishing.
+
+```bash
+cd docs
+make build    # outputs HTML into docs/site/
+```
+
+The `build` target produces a fully-static site (used by CI for docs previews and by GitHub Pages).
+
+---
+
+## 📤 Publishing (CI)
+
+Docs are tested, but not deployed automatically by GitHub Actions on every push to `main`. The workflow runs `cd docs && make build`.
+
+Publishing is done manually by repo maintainers with `make deploy` which publishes the generated site to **GitHub Pages**.
+
+---
+
+## 🔗 Related reading
+
+* [Building Locally](building.md) – how to run the gateway itself

docs/docs/manage/tuning.md

@@ -7,7 +7,7 @@
 > 1. Tune the **runtime environment** via `.env` and configure mcpgateway to use PostgreSQL and Redis.
 > 2. Adjust **Gunicorn** workers & time‑outs in `gunicorn.conf.py`.
 > 3. Right‑size **CPU/RAM** for the container or spin up more instances (with shared Redis state) and change the database settings (ex: connection limits).
-> 4. Benchmark with **hey** (or your favourite load‑generator) before & after.
+> 4. Benchmark with **hey** (or your favourite load‑generator) before & after. See also: [performance testing guide](../testing/performance.md)
 
 ---
 

docs/docs/testing/.pages

@@ -1,3 +1,4 @@
 nav:
   - index.md
   - basic.md
+  - performance.md

docs/docs/testing/performance.md

@@ -0,0 +1,108 @@
+# Performance Testing
+
+Use this guide to benchmark **MCP Gateway** under load, validate performance improvements, and identify bottlenecks before production deployment.
+
+---
+
+## ⚙️ Tooling: `hey`
+
+[`hey`](https://github.com/rakyll/hey) is a CLI-based HTTP load generator. Install it with:
+
+```bash
+brew install hey            # macOS
+sudo apt install hey        # Debian/Ubuntu
+go install github.com/rakyll/hey@latest  # From source
+```
+
+---
+
+## 🎯 Establishing a Baseline
+
+Before benchmarking the full MCP Gateway stack, run tests against the **MCP server directly** (if applicable) to establish baseline latency and throughput. This helps isolate issues related to gateway overhead, authentication, or network I/O.
+
+If your backend service exposes a direct HTTP interface or gRPC gateway, target it with `hey` using the same payload and concurrency settings.
+
+```bash
+hey -n 5000 -c 100 \
+  -m POST \
+  -T application/json \
+  -D tests/hey/payload.json \
+  http://localhost:5000/your-backend-endpoint
+```
+
+Compare the 95/99th percentile latencies and error rates with and without the gateway in front. Any significant increase can guide you toward:
+
+* Bottlenecks in auth middleware
+* Overhead from JSON-RPC wrapping/unwrapping
+* Improper worker/thread config in Gunicorn
+
+## 🚀 Scripted Load Tests: `tests/hey/hey.sh`
+
+A wrapper script exists at:
+
+```bash
+tests/hey/hey.sh
+```
+
+This script provides:
+
+* Strict error handling (`set -euo pipefail`)
+* Helpful CLI interface (`-n`, `-c`, `-d`, etc.)
+* Required dependency checks
+* Optional dry-run mode
+* Timestamped logging
+
+Example usage:
+
+```bash
+./hey.sh -n 10000 -c 200 \
+  -X POST \
+  -T application/json \
+  -H "Authorization: Bearer $JWT" \
+  -d payload.json \
+  -u http://localhost:4444/rpc
+```
+
+> The `payload.json` file is expected to be a valid JSON-RPC request payload.
+
+Sample payload (`tests/hey/payload.json`):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "convert_time",
+  "params": {
+    "source_timezone": "Europe/Berlin",
+    "target_timezone": "Europe/Dublin",
+    "time": "09:00"
+  }
+}
+```
+
+Logs are saved automatically (e.g. `hey-20250610_120000.log`).
+
+---
+
+## 📊 Interpreting Results
+
+When the test completes, look at:
+
+| Metric             | Interpretation                                          |
+| ------------------ | ------------------------------------------------------- |
+| Requests/sec (RPS) | Raw throughput capability                               |
+| 95/99th percentile | Tail latency — tune `timeout`, workers, or DB pooling   |
+| Non-2xx responses  | Failures under load — common with CPU/memory starvation |
+
+---
+
+## 🧪 Tips & Best Practices
+
+* Always test against a **realistic endpoint** (e.g. `POST /rpc` with auth and payload).
+* Use the same JWT and payload structure your clients would.
+* Run from a dedicated machine to avoid local CPU skewing results.
+* Use `make run` or `make serve` to launch the app for local testing.
+
+For runtime tuning details, see [Gateway Tuning Guide](../manage/tuning.md).
+
+---

docs/docs/using/clients/copilot.md

@@ -144,5 +144,3 @@ Expected: Copilot invokes the Gateway's `echo` tool and displays the response.
 * [Copilot Docs](https://github.com/features/copilot)
 
 ---
-
-Would you like this exported as a Markdown file or added to your MkDocs site?

tests/hey/payload2.json

@@ -10,4 +10,4 @@
       "time": "09:00"
     }
   }
-}
+}