diff --git a/README.md b/README.md index 68db5f7..70016ab 100644 --- a/README.md +++ b/README.md @@ -77,11 +77,30 @@ All documentation pages follow this structure: ## Code Highlighting -All pages include highlight.js for automatic syntax highlighting: +All pages use highlight.js for automatic syntax highlighting: -- CSS theme: `github-dark.min.css` (matches dark theme) -- Auto-initialization: `hljs.highlightAll()` -- Custom styles in `style.css` integrate with highlight.js +- **Theme**: `github-dark.min.css` (matches dark theme) +- **Auto-initialization**: `hljs.highlightAll()` runs on page load +- **Custom styles**: Enhanced color palette in `style.css` +- **Languages detected**: YAML, Bash, Python, Plaintext + +### Code Block Format + +All code blocks use semantic language classes: + +```html +

+server:
+  host: 0.0.0.0
+  port: 8080
+
+``` + +Supported languages: +- `language-yaml` — YAML configuration files +- `language-bash` — Shell commands and scripts +- `language-python` — Python code examples +- `language-plaintext` — Plain text output ## Deployment diff --git a/getting-started/installation.html b/getting-started/installation.html index 4dc1f09..09bdaaa 100644 --- a/getting-started/installation.html +++ b/getting-started/installation.html @@ -32,32 +32,32 @@

Install from Release (Recommended)

Download the latest wheel file from Git Releases and install it:

-
# Download the wheel file from releases
-# Example: pyserve-0.7.0-py3-none-any.whl
+        
# Download the wheel file from releases
+# Example: pyserve-0.7.0-py3-none-any.whl
 
-pip install pyserve-0.7.0-py3-none-any.whl
+pip install pyserve-0.7.0-py3-none-any.whl

After installation, the pyserve command will be available in your terminal:

-
pyserve --version
+
pyserve --version

Install from Source

For development or if you want the latest changes:

-
# Clone the repository
+        
# Clone the repository
 git clone https://github.com/ShiftyX1/PyServe.git
 cd PyServe
 
-# Install with Poetry (recommended for development)
+# Install with Poetry (recommended for development)
 make init
 
-# Or build and install the package
+# Or build and install the package
 make build
-pip install dist/pyserve-*.whl
+pip install dist/pyserve-*.whl

Verify Installation

Check that pyserve is installed correctly:

-
pyserve --version
-# Output: pyserve 0.7.0
+
pyserve --version
+# Output: pyserve 0.7.0

Dependencies

pyserve automatically installs the following dependencies:

diff --git a/getting-started/quickstart.html b/getting-started/quickstart.html index 422a00f..1e27a87 100644 --- a/getting-started/quickstart.html +++ b/getting-started/quickstart.html @@ -28,37 +28,37 @@

1. Create Configuration File

Create a file named config.yaml in your project directory:

-
http:
-  static_dir: ./static
-  templates_dir: ./templates
+        
http:
+  static_dir: ./static
+  templates_dir: ./templates
 
-server:
-  host: 0.0.0.0
-  port: 8080
+server:
+  host: 0.0.0.0
+  port: 8080
 
-logging:
-  level: INFO
-  console_output: true
+logging:
+  level: INFO
+  console_output: true
 
-extensions:
-  - type: routing
-    config:
-      regex_locations:
-        "__default__":
-          root: "./static"
-          index_file: "index.html"
+extensions: + - type: routing + config: + regex_locations: + "__default__": + root: "./static" + index_file: "index.html"

2. Create Static Directory

Create a static folder and add an index.html:

-
mkdir -p static
-echo '<h1>Hello from pyserve!</h1>' > static/index.html
+
mkdir -p static
+echo '<h1>Hello from pyserve!</h1>' > static/index.html

3. Start the Server

-
pyserve
+
pyserve

You should see output like:

-
Starting PyServe server on 0.0.0.0:8080
+
Starting PyServe server on 0.0.0.0:8080

4. Open in Browser

Navigate to http://localhost:8080 — you should see your page!

@@ -66,44 +66,44 @@ echo '<h1>Hello from pyserve!</h1>' > static/index.html

Using CLI Options

Override configuration via command line:

-
# Use a different config file
+        
# Use a different config file
 pyserve -c /path/to/config.yaml
 
-# Override host and port
+# Override host and port
 pyserve --host 127.0.0.1 --port 9000
 
-# Enable debug mode (verbose logging)
-pyserve --debug
+# Enable debug mode (verbose logging) +pyserve --debug

Example: Serve Documentation

Serve a documentation directory with proper caching:

-
http:
-  static_dir: ./docs
+        
http:
+  static_dir: ./docs
 
-server:
-  host: 0.0.0.0
-  port: 8000
+server:
+  host: 0.0.0.0
+  port: 8000
 
-extensions:
-  - type: routing
-    config:
-      regex_locations:
-        "=/":
-          root: "./docs"
-          index_file: "index.html"
+extensions:
+  - type: routing
+    config:
+      regex_locations:
+        "=/":
+          root: "./docs"
+          index_file: "index.html"
         
-        "~*\\.(css|js)$":
-          root: "./docs"
-          cache_control: "public, max-age=3600"
+        "~*\\.(css|js)$":
+          root: "./docs"
+          cache_control: "public, max-age=3600"
         
-        "~*\\.html$":
-          root: "./docs"
-          cache_control: "no-cache"
+        "~*\\.html$":
+          root: "./docs"
+          cache_control: "no-cache"
         
-        "__default__":
-          root: "./docs"
-          index_file: "index.html"
+ "__default__": + root: "./docs" + index_file: "index.html"
Next Steps: diff --git a/guides/asgi-mount.html b/guides/asgi-mount.html index da3df53..8ad7da8 100644 --- a/guides/asgi-mount.html +++ b/guides/asgi-mount.html @@ -45,15 +45,15 @@

Configuration

ASGI applications are mounted via the asgi extension:

-
extensions:
-  - type: asgi
-    config:
-      mounts:
-        - path: "/api"
-          app_path: "myapp.api:app"
-          app_type: asgi
-          name: "api-app"
-          strip_path: true
+
extensions:
+  - type: asgi
+    config:
+      mounts:
+        - path: "/api"
+          app_path: "myapp.api:app"
+          app_type: asgi
+          name: "api-app"
+          strip_path: true

Mount Configuration Options

@@ -85,23 +85,23 @@

Mounting FastAPI

FastAPI applications are native ASGI:

-
# myapp/api.py
+        
# myapp/api.py
 from fastapi import FastAPI
 
 app = FastAPI()
 
 @app.get("/users")
 async def get_users():
-    return [{"id": 1, "name": "Alice"}]
+ return [{"id": 1, "name": "Alice"}]
-
extensions:
-  - type: asgi
-    config:
-      mounts:
-        - path: "/api"
-          app_path: "myapp.api:app"
-          app_type: asgi
-          name: "fastapi-app"
+
extensions:
+  - type: asgi
+    config:
+      mounts:
+        - path: "/api"
+          app_path: "myapp.api:app"
+          app_type: asgi
+          name: "fastapi-app"

With this configuration:

Architecture

-
+        

                     PyServe Gateway (:8000)
                            │
           ┌────────────────┼────────────────┐
@@ -49,25 +49,25 @@
       FastAPI          Flask           Starlette
        :9001           :9002             :9003
       /api/*          /admin/*           /ws/*
-        
+

PyServe acts as a gateway, routing requests to the appropriate subprocess based on URL path.

Basic Configuration

-
server:
-  host: 0.0.0.0
-  port: 8000
+        
server:
+  host: 0.0.0.0
+  port: 8000
 
-extensions:
-  - type: process_orchestration
-    config:
-      apps:
-        - name: api
-          path: /api
-          app_path: myapp.api:app
+extensions:
+  - type: process_orchestration
+    config:
+      apps:
+        - name: api
+          path: /api
+          app_path: myapp.api:app
           
-        - name: admin
-          path: /admin
-          app_path: myapp.admin:app
+ - name: admin + path: /admin + app_path: myapp.admin:app

App Configuration Options

@@ -130,18 +130,18 @@

Global Configuration

-
extensions:
-  - type: process_orchestration
-    config:
-      port_range: [9000, 9999]
-      health_check_enabled: true
-      proxy_timeout: 60.0
-      logging:
-        httpx_level: warning
-        proxy_logs: true
-        health_check_logs: false
-      apps:
-        # ...
+
extensions:
+  - type: process_orchestration
+    config:
+      port_range: [9000, 9999]
+      health_check_enabled: true
+      proxy_timeout: 60.0
+      logging:
+        httpx_level: warning
+        proxy_logs: true
+        health_check_logs: false
+      apps:
+        # ...
port_range
@@ -161,7 +161,7 @@

FastAPI Example

-
# myapp/api.py
+        
# myapp/api.py
 from fastapi import FastAPI
 
 app = FastAPI()
@@ -172,22 +172,22 @@ async def health():
 
 @app.get("/users")
 async def get_users():
-    return [{"id": 1, "name": "Alice"}]
+ return [{"id": 1, "name": "Alice"}]
-
extensions:
-  - type: process_orchestration
-    config:
-      apps:
-        - name: api
-          path: /api
-          app_path: myapp.api:app
-          workers: 4
-          health_check_path: /health
+
extensions:
+  - type: process_orchestration
+    config:
+      apps:
+        - name: api
+          path: /api
+          app_path: myapp.api:app
+          workers: 4
+          health_check_path: /health

Requests to /api/users are proxied to the FastAPI process as /users.

Flask Example (WSGI)

-
# myapp/admin.py
+        
# myapp/admin.py
 from flask import Flask
 
 app = Flask(__name__)
@@ -198,17 +198,17 @@ def health():
 
 @app.route("/dashboard")
 def dashboard():
-    return {"page": "dashboard"}
+ return {"page": "dashboard"}
-
extensions:
-  - type: process_orchestration
-    config:
-      apps:
-        - name: admin
-          path: /admin
-          app_path: myapp.admin:app
-          app_type: wsgi
-          workers: 2
+
extensions:
+  - type: process_orchestration
+    config:
+      apps:
+        - name: admin
+          path: /admin
+          app_path: myapp.admin:app
+          app_type: wsgi
+          workers: 2
Note: WSGI support requires a2wsgi package: @@ -216,7 +216,7 @@ def dashboard():

Factory Pattern

-
# myapp/api.py
+        
# myapp/api.py
 from fastapi import FastAPI
 
 def create_app(debug: bool = False) -> FastAPI:
@@ -226,49 +226,49 @@ def create_app(debug: bool = False) -> FastAPI:
     async def health():
         return {"status": "ok", "debug": debug}
     
-    return app
+ return app
-
apps:
-  - name: api
-    path: /api
-    app_path: myapp.api:create_app
-    factory: true
+
apps:
+  - name: api
+    path: /api
+    app_path: myapp.api:create_app
+    factory: true

Environment Variables

Pass environment variables to subprocesses:

-
apps:
-  - name: api
-    path: /api
-    app_path: myapp.api:app
-    env:
-      DATABASE_URL: "postgresql://localhost/mydb"
-      REDIS_URL: "redis://localhost:6379"
-      DEBUG: "false"
+
apps:
+  - name: api
+    path: /api
+    app_path: myapp.api:app
+    env:
+      DATABASE_URL: "postgresql://localhost/mydb"
+      REDIS_URL: "redis://localhost:6379"
+      DEBUG: "false"

Multiple Applications

-
extensions:
-  - type: process_orchestration
-    config:
-      port_range: [9000, 9999]
-      apps:
-        # FastAPI REST API
-        - name: api
-          path: /api
-          app_path: apps.api:app
-          workers: 4
+        
extensions:
+  - type: process_orchestration
+    config:
+      port_range: [9000, 9999]
+      apps:
+        # FastAPI REST API
+        - name: api
+          path: /api
+          app_path: apps.api:app
+          workers: 4
         
-        # Flask Admin Panel
-        - name: admin
-          path: /admin
-          app_path: apps.admin:app
-          app_type: wsgi
-          workers: 2
+        # Flask Admin Panel
+        - name: admin
+          path: /admin
+          app_path: apps.admin:app
+          app_type: wsgi
+          workers: 2
         
-        # Starlette WebSocket Handler
-        - name: websocket
-          path: /ws
-          app_path: apps.websocket:app
-          workers: 1
+ # Starlette WebSocket Handler + - name: websocket + path: /ws + app_path: apps.websocket:app + workers: 1

Request Tracing

PyServe automatically generates and propagates X-Request-ID headers:

diff --git a/guides/reverse-proxy.html b/guides/reverse-proxy.html index acd152f..412d4a6 100644 --- a/guides/reverse-proxy.html +++ b/guides/reverse-proxy.html @@ -28,12 +28,12 @@

Basic Proxy Configuration

Use the proxy_pass directive in routing:

-
extensions:
-  - type: routing
-    config:
-      regex_locations:
-        "~^/api/":
-          proxy_pass: "http://localhost:9001"
+
extensions:
+  - type: routing
+    config:
+      regex_locations:
+        "~^/api/":
+          proxy_pass: "http://localhost:9001"

All requests to /api/* will be forwarded to http://localhost:9001/api/*.

@@ -62,21 +62,21 @@

Custom Headers

Add custom headers to proxied requests:

-
"~^/api/":
-  proxy_pass: "http://localhost:9001"
-  headers:
-    - "X-Custom-Header: my-value"
-    - "Authorization: Bearer token123"
+
"~^/api/":
+  proxy_pass: "http://localhost:9001"
+  headers:
+    - "X-Custom-Header: my-value"
+    - "Authorization: Bearer token123"

Dynamic Headers with Captures

Use regex capture groups to build dynamic headers:

-
"~^/api/v(?P<version>\\d+)/(?P<service>\\w+)":
-  proxy_pass: "http://localhost:9001"
-  headers:
-    - "X-API-Version: {version}"
-    - "X-Service: {service}"
-    - "X-Client-IP: $remote_addr"
+
"~^/api/v(?P<version>\\d+)/(?P<service>\\w+)":
+  proxy_pass: "http://localhost:9001"
+  headers:
+    - "X-API-Version: {version}"
+    - "X-Service: {service}"
+    - "X-Client-IP: $remote_addr"

Special variables:

-
- type: asgi
-  config:
-    mounts:
-      # FastAPI application
-      - path: "/api"
-        app_path: "myapp.api:app"
-        app_type: asgi
-        name: "api"
+        
- type: asgi
+  config:
+    mounts:
+      # FastAPI application
+      - path: "/api"
+        app_path: "myapp.api:app"
+        app_type: asgi
+        name: "api"
       
-      # Flask application (WSGI)
-      - path: "/admin"
-        app_path: "myapp.admin:app"
-        app_type: wsgi
-        name: "admin"
+      # Flask application (WSGI)
+      - path: "/admin"
+        app_path: "myapp.admin:app"
+        app_type: wsgi
+        name: "admin"
       
-      # Factory pattern with arguments
-      - path: "/api/v2"
-        app_path: "myapp.api:create_app"
-        factory: true
-        factory_args:
-          debug: true
-          version: "2.0"
+ # Factory pattern with arguments + - path: "/api/v2" + app_path: "myapp.api:create_app" + factory: true + factory_args: + debug: true + version: "2.0"

Supported frameworks:

-
- type: process_orchestration
-  config:
-    port_range: [9000, 9999]
-    health_check_enabled: true
-    proxy_timeout: 60.0
-    logging:
-      httpx_level: warning
-      proxy_logs: true
-      health_check_logs: false
-    apps:
-      - name: api
-        path: /api
-        app_path: myapp.api:app
-        workers: 4
-        health_check_path: /health
+        
- type: process_orchestration
+  config:
+    port_range: [9000, 9999]
+    health_check_enabled: true
+    proxy_timeout: 60.0
+    logging:
+      httpx_level: warning
+      proxy_logs: true
+      health_check_logs: false
+    apps:
+      - name: api
+        path: /api
+        app_path: myapp.api:app
+        workers: 4
+        health_check_path: /health
       
-      - name: admin
-        path: /admin
-        app_path: myapp.admin:app
-        app_type: wsgi
-        workers: 2
+ - name: admin + path: /admin + app_path: myapp.admin:app + app_type: wsgi + workers: 2

App Configuration

diff --git a/style.css b/style.css index 34427e2..869d726 100644 --- a/style.css +++ b/style.css @@ -221,21 +221,6 @@ dd { text-align: center; } -/* Syntax highlighting for config examples */ -.directive { - color: #5fba7d; - font-weight: bold; -} - -.value { - color: #87ceeb; -} - -.comment { - color: #666; - font-style: italic; -} - /* Main wrapper for two-column layout */ #main-wrapper { display: flex;