Introducing mkdocs

.gitignore

@@ -5,4 +5,9 @@
 /.tox/
 __pycache__/
 *.pyc
-venv/
+venv/
+# MkDocs build output
+site/
+.cache/
+docs/_build/
+docs/.buildinfo

Makefile

@@ -3,6 +3,15 @@
 install:
 	pip install -e .
 
+install-docs:
+	pip install -e ".[dev,docs]"
+
+docs-serve:
+	mkdocs serve
+
+docs-build:
+	mkdocs build
+
 test:
 	httphound -l debug example_tests
 

docs/api/base-proxy-test.md

@@ -0,0 +1,14 @@
+# BaseProxyTest API
+
+::: httphound.main.BaseProxyTest
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - __init__
+        - setup
+        - teardown
+        - make_request
+        - validate_response
+        - run_test
+        - execute

docs/cli.md

@@ -0,0 +1 @@
+TODO

docs/contributing.md

@@ -0,0 +1 @@
+TODO

docs/getting-started/installation.md

@@ -0,0 +1,32 @@
+# Installation
+
+## Requirements
+
+- Python 3.9 or higher
+- HAProxy binary (must be available on your system)
+
+## Install HttpHound
+
+### From Source
+```bash
+git clone https://gitlab.wikimedia.org/repos/sre/httphound.git
+cd httphound
+pip install -e .
+```
+
+### With Development Dependencies
+```bash
+pip install -e ".[dev,docs]"
+```
+
+## Verify Installation
+```bash
+httphound --help
+```
+
+## Install HAProxy
+
+### Debian
+```bash
+sudo apt-get install haproxy
+```

docs/getting-started/quickstart.md

@@ -0,0 +1,71 @@
+# Quick Start
+
+Get started with HttpHound
+
+## 1. Create a Test File
+
+Create `my_test.py`:
+```python
+from httphound.main import BaseProxyTest, ProxyConfig
+from pathlib import Path
+
+class BasicTest(BaseProxyTest):
+    def __init__(self):
+        super().__init__()
+        self.description = "My first test"
+        self.url = "http://127.0.0.1:4242"
+        self.expected_status = 200
+        
+        self.proxy_config = ProxyConfig(
+            binary_path="/usr/sbin/haproxy"  # Adjust path
+        )
+    
+    async def run_test(self):
+        await self.make_request()
+        return True
+```
+
+## 2. Run the Test
+```bash
+httphound my_test.py
+```
+
+## 3. View Results
+
+You should see output like:
+```
+2026-03-24 08:02:21,277 - httphound.main - INFO - Starting httphound (async version)
+2026-03-24 08:02:21,277 - httphound.main - INFO - Discovered 1 tests in ['my_test.py']
+2026-03-24 08:02:21,277 - httphound.main - INFO - Running tests sequentially
+2026-03-24 08:02:21,277 - httphound.main - INFO - Running test: BasicTest
+2026-03-24 08:02:21,277 - httphound.backend - INFO - Backend listening on 127.0.0.1:9999
+2026-03-24 08:02:21,429 - httphound.proxy - INFO - Proxy started with PID 907
+2026-03-24 08:02:21,469 - aiohttp.access - INFO - 127.0.0.1 [24/Mar/2026:08:02:21 +0100] "GET / HTTP/1.1" 200 154 "-" "python-httpx/0.28.1"
+2026-03-24 08:02:21,469 - httpx - INFO - HTTP Request: GET http://127.0.0.1:4242 "HTTP/1.1 200 OK"
+2026-03-24 08:02:21,482 - aiohttp.access - INFO - 127.0.0.1 [24/Mar/2026:08:02:21 +0100] "GET / HTTP/1.1" 200 154 "-" "python-httpx/0.28.1"
+2026-03-24 08:02:21,482 - httpx - INFO - HTTP Request: GET http://127.0.0.1:4242 "HTTP/1.1 200 OK"
+2026-03-24 08:02:21,482 - httphound.backend - INFO - Backend stopped successfully
+2026-03-24 08:02:21,545 - httphound.proxy - INFO - Proxy stopped
+
+TEST EXECUTION SUMMARY
+================================================================================
+
+================================================================================
+Status    Name           Description      Duration (s)
+--------  -------------  -------------  --------------
+PASS      BasicTest      Basic request           0.205
+
+================================================================================
+  Total Tests    Passed    Failed    Total Duration (s)
+-------------  --------  --------  --------------------
+            1         1         0                 0.205
+================================================================================
+
+
+```
+
+## Next Steps
+
+- [Write more complex tests](../user-guide/writing-tests.md)
+- [Explore validation options](../user-guide/validation.md)
+

docs/index.md

@@ -0,0 +1,50 @@
+# HttpHound
+
+Welcome to HttpHound documentation!
+
+HttpHound is a Python framework for testing HTTP reverse proxies, with a specific focus on HAProxy.
+
+## Features
+
+- Tests defined as Python classes
+- Automatic backend spawning
+- Reverse proxy config generation from templates
+- Comprehensive validation (status, headers, body)
+- Backend request inspection
+- Async/await support
+
+## Quick Links
+
+- [Installation](getting-started/installation.md)
+- [Quick Start](getting-started/quickstart.md)
+- [Writing Tests](user-guide/writing-tests.md)
+- [API Reference](api/base-proxy-test.md)
+
+## Example
+```python
+from httphound.main import BaseProxyTest, ProxyConfig
+from pathlib import Path
+
+class MyTest(BaseProxyTest):
+    def __init__(self):
+        super().__init__()
+        self.description = "Basic test"
+        self.expected_status = 200
+        self.proxy_config = ProxyConfig(
+            binary_path=Path.home() / "bin/haproxy"
+        )
+    
+    async def run_test(self):
+        await self.make_request()
+        return True
+```
+
+## Installation
+```bash
+pip install httphound
+```
+
+## Running Tests
+```bash
+httphound example_tests/
+```

docs/troubleshooting.md

@@ -0,0 +1 @@
+TODO

httphound/backend.py

@@ -1,8 +1,3 @@
-"""
-Async Backend Module - HttpHound
-Manages backend lifecycle using pure async/await patterns
-"""
-
 import logging
 import asyncio
 

httphound/main.py

@@ -450,7 +450,7 @@ async def async_main(args):
     
     # ASCII art only in debug mode
     if args.log_level == 'DEBUG':
-        hound = '''
+        hound = r'''
           __
  \ ______/ V`-,
   }        /~~

httphound/proxy.py

@@ -1,7 +1,3 @@
-"""
-Manages all proxy-related stuff
-Enhanced with async health checking
-"""
 import logging
 import os
 import subprocess

mkdocs.yml

@@ -0,0 +1,112 @@
+site_name: HttpHound Documentation
+site_description: HTTP reverse proxy testing framework
+site_author: Fabrizio Furnari
+site_url: https://gitlab.wikimedia.org/repos/sre/httphound/
+
+# Repository
+repo_name: sre/httphound
+repo_url: https://gitlab.wikimedia.org/repos/sre/httphound/
+edit_uri: edit/main/docs/
+
+# Theme configuration
+theme:
+  name: material
+  palette:
+    # Light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - content.code.copy
+    - content.code.annotate
+  
+  icon:
+    repo: fontawesome/brands/git-alt
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - footnotes
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+# Plugins
+plugins:
+  - search
+  - autorefs
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            docstring_style: google
+            show_source: true
+            show_root_heading: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            members_order: source
+            separate_signature: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+
+# Navigation structure
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quickstart.md
+  
+  - User Guide:
+    - Writing Tests: user-guide/writing-tests.md
+    - Validation Options: user-guide/validation.md
+    - Backend Configuration: user-guide/backend-config.md
+    - Proxy Configuration: user-guide/proxy-config.md
+  
+  - API Reference:
+    - BaseProxyTest: api/base-proxy-test.md
+    - Configuration: api/configuration.md
+    - Test Runner: api/test-runner.md
+    - Validation: api/validation.md
+  
+  - CLI Reference: cli.md
+  - Troubleshooting: troubleshooting.md
+  - Contributing: contributing.md
+
+# Extra
+extra:
+  version:
+    provider: mike  # For versioned docs (optional)
+
+watch:
+  - docs

setup.py

@@ -12,6 +12,21 @@ SETUP_REQUIRES = [
     'setuptools_scm>=3.2.0',
 ]
 
+EXTRA_REQUIRES = {
+    'docs': [
+        "click==8.2.1",
+        'mkdocs>=1.5.0',
+        'mkdocs-material>=9.0.0',
+        'mkdocstrings[python]>=0.24.0',
+        'mkdocs-autorefs>=0.5.0',
+        'pymdown-extensions>=10.0',
+    ],
+    'dev': [
+        'pytest>=7.0.0',
+        'pytest-asyncio>=0.21.0',
+    ],
+}
+
 setup(
     author='Fabrizio Furnari',
     author_email='ffurnari@wikimedia.org',
@@ -20,6 +35,7 @@ setup(
     name='httphound',
     packages=find_packages(exclude=["test_*"]),
     setup_requires=SETUP_REQUIRES,
+    extras_require=EXTRA_REQUIRES,
     url='https://gitlab.wikimedia.org/repos/sre/httphound',
     use_scm_version=True,
     entry_points={