Hayhooks documentation website

.env.example

@@ -1,10 +1,10 @@
-# Host for the FastAPI app
+# Hayhooks Host
 HAYHOOKS_HOST="localhost"
 
-# Port for the FastAPI app
+# Hayhooks Port
 HAYHOOKS_PORT=1416
 
-# Root path for the FastAPI app
+# Root path
 HAYHOOKS_ROOT_PATH=""
 
 # Path to the directory containing the pipelines

CONTRIBUTING_DOCS.md

@@ -0,0 +1,262 @@
+# Documentation Development
+
+This guide covers how to work with and contribute to the Hayhooks documentation.
+
+## Prerequisites
+
+- Python 3.9+
+- Hatch installed (`pip install hatch`)
+
+## Building Documentation
+
+### Using Hatch (Recommended)
+
+The documentation can be built and served using Hatch commands:
+
+#### Development Server (Recommended)
+
+Start a local development server with live reloading using the dedicated docs environment:
+
+```bash
+# Using the dedicated docs environment (auto-installs all dependencies)
+hatch run docs:serve
+
+# With custom options
+hatch run docs:serve --open --dirty
+```
+
+The server will be available at `http://localhost:8000/hayhooks/`
+
+#### Build Production Site
+
+Build the documentation for deployment:
+
+```bash
+# Using the docs environment (recommended)
+hatch run docs:build
+
+# Clean build (removes old files first)
+hatch run docs:build --clean
+
+# Strict build (fails on warnings)
+hatch run docs:build --strict
+```
+
+The built site will be available in the `site/` directory.
+
+#### Deploy Documentation
+
+Deploy the documentation to GitHub Pages:
+
+```bash
+# Deploy to GitHub Pages
+hatch run docs:deploy
+
+# With custom options
+hatch run docs:deploy --force
+```
+
+### Direct MkDocs Usage
+
+If you prefer to use MkDocs directly:
+
+```bash
+# Install dependencies
+pip install mkdocs-material
+
+# Serve documentation
+mkdocs serve
+
+# Build documentation
+mkdocs build
+```
+
+## Documentation Structure
+
+```text
+docs/
+├── mkdocs.yml                 # Main configuration
+├── index.md                   # Homepage
+├── getting-started/           # Getting started guides
+├── concepts/                  # Core concepts
+├── features/                  # Feature documentation
+├── advanced/                  # Advanced topics
+├── deployment/                # Deployment guides
+├── examples/                  # Example documentation
+├── reference/                 # Reference documentation
+├── about/                     # About information
+├── assets/                    # Images and static assets
+├── stylesheets/               # Custom CSS
+└── javascripts/               # Custom JavaScript
+```
+
+## Adding New Documentation
+
+### 1. Create New Files
+
+Add new Markdown files in the appropriate directory:
+
+```bash
+# Create a new feature document
+touch docs/features/new-feature.md
+
+# Create a new example
+touch docs/examples/new-example.md
+```
+
+### 2. Update Navigation
+
+Update `mkdocs.yml` to include your new documentation in the navigation:
+
+```yaml
+nav:
+  - Features:
+    - New Feature: features/new-feature.md  # Add this line
+    - OpenAI Compatibility: features/openai-compatibility.md
+    - MCP Support: features/mcp-support.md
+```
+
+### 3. Add Images
+
+Place images in the `docs/assets/` directory:
+
+```bash
+# Add an image
+mv screenshot.png docs/assets/
+
+# Reference in Markdown
+![Screenshot](../assets/screenshot.png)
+```
+
+## Documentation Style Guide
+
+### Writing Style
+
+- Use clear, concise language
+- Include practical examples
+- Provide step-by-step instructions
+- Use proper Markdown formatting
+
+### Avoiding Redundancy
+
+To maintain consistency and reduce maintenance burden:
+
+- **Single Source of Truth**: Each topic should have one canonical location
+  - README.md: Quick overview and getting started examples
+  - docs/concepts/: Detailed conceptual explanations
+  - docs/reference/: Complete API and configuration references
+
+- **Cross-Referencing**: Link to the canonical source instead of duplicating content
+  - Good: "For complete configuration options, see [Environment Variables Reference](../reference/environment-variables.md)"
+  - Bad: Copying all environment variables into multiple pages
+
+- **Next Steps**: Keep to 2-3 most relevant links per page
+  - Focus on logical next actions for the reader
+  - Avoid circular references (page A → page B → page A)
+
+### Code Examples
+
+Use proper code block formatting:
+
+```python
+# Python code
+def example_function():
+    return "Hello, World!"
+```
+
+```bash
+# Shell commands
+hatch run docs-serve
+```
+
+### Links
+
+- **Internal Documentation**: Use relative links (e.g., `../concepts/pipeline-wrapper.md`)
+- **External Resources**: Use absolute links (e.g., `https://haystack.deepset.ai/`)
+- **README Links**: When linking from docs to README, use absolute GitHub URLs
+- **Test Links**: Always verify links work before committing
+
+## Testing Documentation
+
+### Build Verification
+
+Always test the documentation builds successfully:
+
+```bash
+hatch run docs:build --strict
+```
+
+### Link Verification
+
+Check for broken links:
+
+```bash
+# Test locally
+hatch run docs:serve
+
+# Or use a link checker tool
+pip install linkchecker
+linkchecker http://localhost:8000/hayhooks/
+```
+
+### Preview Changes
+
+Preview your changes in the browser:
+
+```bash
+hatch run docs:serve --open
+```
+
+## Deployment
+
+### GitHub Pages
+
+> **Note:** Automatic deployment via GitHub Actions is not yet configured. For now, documentation must be deployed manually. A GitHub Actions workflow will be added in the future.
+
+### Manual Deployment
+
+To deploy manually:
+
+```bash
+# Deploy to GitHub Pages (builds and deploys in one command)
+hatch run docs:deploy
+
+# Or build only without deploying
+hatch run docs:build
+# The site is now ready in the site/ directory
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Build Fails**
+   - Check for Markdown syntax errors
+   - Verify all links are valid
+   - Ensure image paths are correct
+
+2. **Navigation Issues**
+   - Check `mkdocs.yml` syntax
+   - Verify all referenced files exist
+   - Test navigation structure
+
+3. **Style Issues**
+   - Check CSS file paths
+   - Verify JavaScript syntax
+   - Test in multiple browsers
+
+### Getting Help
+
+- Check MkDocs documentation: <https://www.mkdocs.org/>
+- Review Material theme docs: <https://squidfunk.github.io/mkdocs-material/>
+- Open an issue on GitHub: <https://github.com/deepset-ai/hayhooks/issues>
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your documentation changes
+4. Test locally with `hatch run docs:serve`
+5. Submit a pull request
+
+Thank you for contributing to Hayhooks documentation!

README.md

@@ -157,7 +157,12 @@ LOG=debug
 The `hayhooks` package provides a CLI to manage the server and the pipelines.
 Any command can be run with `hayhooks <command> --help` to get more information.
 
-CLI commands are basically wrappers around the HTTP API of the server. The full API reference is available at [//HAYHOOKS_HOST:HAYHOOKS_PORT/docs](http://HAYHOOKS_HOST:HAYHOOKS_PORT/docs) or [//HAYHOOKS_HOST:HAYHOOKS_PORT/redoc](http://HAYHOOKS_HOST:HAYHOOKS_PORT/redoc).
+CLI commands are basically wrappers around the HTTP API of the server. The full API reference is available interactively at:
+
+- **Swagger UI**: `http://localhost:1416/docs` - Interactive API explorer with built-in request testing
+- **ReDoc**: `http://localhost:1416/redoc` - Clean, responsive API documentation
+
+You can also access the OpenAPI schema at `http://localhost:1416/openapi.json`.
 
 ```shell
 hayhooks run     # Start the server
@@ -726,9 +731,7 @@ Or if you need to use the SSE transport:
 }
 ```
 
-After adding the MCP Server, you should see the Hayhooks Core MCP Tools in the list of available tools:
-
-![cursor-mcp-settings](./docs/assets/cursor-mcp-settings.png)
+After adding the MCP Server, you should see the Hayhooks Core MCP Tools in the list of available tools.
 
 Now in the Cursor chat interface you can use the Hayhooks Core MCP Tools by mentioning them in your messages.
 
@@ -1111,8 +1114,6 @@ We have some dedicated documentation for deployment:
 - Docker-based deployments: <https://docs.haystack.deepset.ai/docs/docker>
 - Kubernetes-based deployments: <https://docs.haystack.deepset.ai/docs/kubernetes>
 
-We also have some additional deployment guidelines, see [deployment_guidelines.md](docs/deployment_guidelines.md).
-
 ### License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

docs/about/license.md

@@ -0,0 +1,21 @@
+# License
+
+Hayhooks is open-source software released under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+## Trademarks
+
+Haystack and the Haystack logo are trademarks of [deepset GmbH](https://www.deepset.ai/). All other trademarks are the property of their respective owners.
+
+## Contact
+
+For licensing questions or inquiries:
+
+- Email: <info@deepset.ai>
+- Website: <https://deepset.ai>
+- GitHub: <https://github.com/deepset-ai/hayhooks>
+
+## Additional Resources
+
+- [Apache License 2.0 FAQ](https://www.apache.org/foundation/license-faq.html)
+- [Open Source Initiative](https://opensource.org/)
+- [Software Freedom Law Center](https://www.softwarefreedom.org/)

docs/advanced/advanced-configuration.md

@@ -0,0 +1,58 @@
+# Advanced Configuration
+
+This guide covers programmatic customization, custom routes, and middleware for advanced Hayhooks usage.
+
+For basic configuration, see [Configuration](../getting-started/configuration.md). For deployment and performance tuning, see [Deployment Guidelines](../deployment/deployment_guidelines.md).
+
+## Custom Routes and Middleware
+
+### When to add custom routes
+
+- Add specialized endpoints for application-specific logic
+- Provide admin/operations endpoints (restart, status, maintenance tasks)
+- Expose health checks, metrics, and webhook handlers for integrations
+- Implement authentication/authorization flows
+- Offer file management or other utility endpoints
+
+### When to add middleware
+
+- Apply cross-cutting concerns (logging/tracing, correlation IDs)
+- Enforce security controls (authn/z, rate limiting, quotas)
+- Control headers, CORS, compression, and caching
+- Normalize inputs/outputs and error handling consistently
+
+## Programmatic Customization
+
+You can create a custom Hayhooks app instance to add routes or middleware:
+
+```python
+import uvicorn
+from hayhooks.settings import settings
+from fastapi import Request
+from hayhooks import create_app
+
+# Create the Hayhooks app
+hayhooks = create_app()
+
+# Add a custom route
+@hayhooks.get("/custom")
+async def custom_route():
+    return {"message": "Custom route"}
+
+# Add custom middleware
+@hayhooks.middleware("http")
+async def custom_middleware(request: Request, call_next):
+    response = await call_next(request)
+    response.headers["X-Custom-Header"] = "value"
+    return response
+
+if __name__ == "__main__":
+    uvicorn.run("app:hayhooks", host=settings.host, port=settings.port)
+```
+
+This allows you to build custom applications with Hayhooks as the core engine while adding your own business logic and integrations.
+
+## Next Steps
+
+- [Deployment Guidelines](../deployment/deployment_guidelines.md) - Performance tuning, workers, scaling, and deployment strategies
+- [Code Sharing](code-sharing.md) - Reusable components across pipelines