humanprotocol · portuu3 · Jan 13, 2026 · Dec 4, 2025 · Dec 4, 2025 · Dec 5, 2025
diff --git a/.github/workflows/cd-gitbook-sdk-docs.yaml b/.github/workflows/cd-gitbook-sdk-docs.yaml
diff --git a/.gitignore b/.gitignore
@@ -55,3 +55,7 @@ cache
 
 # Ignore developer-only local files
 .local
+
+
+docs/ts
+docs/python
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,42 @@
+# SDK Docs workflow
+
+## Prerequisites
+- `pip install -r docs/requirements.txt`
+- `yarn install`
+- `yarn build:libs`
+
+## Local preview
+- TypeScript docs: `mkdocs serve -f docs/mkdocs-ts.yaml`
+- Python docs: `mkdocs serve -f docs/mkdocs-python.yaml`
+
+## Deploying a new version (mike)
+- TypeScript:  
+  `yarn workspace @human-protocol/sdk build:doc`  
+  `mike deploy -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`  
+  `mike set-default -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`
+- Python:  
+  `mike deploy -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`  
+  `mike set-default -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`
+
+## Deleting a deployed version
+- TypeScript: `mike delete -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`
+- Python: `mike delete -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`
+
+## Landing page (docs/index.html)
+- If you edit `docs/index.html`, apply the change both on your working branch and on `gh-pages`. 
+
+NEVER MERGE THE BRANCHES: `gh-pages` only contains docs builds, not the monorepo code.
+
+## Serving static files
+- Serve only `index.html` (SDK docs won’t load): from `docs/`, run  
+  `python -m http.server 8080 --bind 127.0.0.1`
+- Serve the full published docs: create a mike deployment, switch to the `gh-pages` branch, go to `docs/`, then run  
+  `python -m http.server 8080 --bind 127.0.0.1`
+
+## Repository structure (docs)
+- `docs/index.html`: Static landing page that links to SDK docs (TS/Python).
+- `docs/mkdocs-ts.yaml`: MkDocs config for the TypeScript site (deploys under `docs/ts` via mike).
+- `docs/mkdocs-python.yaml`: MkDocs config for the Python site (deploys under `docs/python` via mike).
+- `docs/ts/`: TypeScript site output; versioned builds live under `docs/ts/<version>` with per-version assets in `docs/ts/<version>/assets/`.
+- `docs/python/`: Python site output (if published); versioned builds live under `docs/python/<version>`.
+- `docs/overrides/`: Shared MkDocs theme overrides and assets (logo/header partials and images).
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,218 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>HUMAN Protocol SDKs</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      body {
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        margin: 0;
+        padding: 0;
+        background: #050319;
+        color: #f6f3ff;
+      }
+      .sdk-hero {
+        max-width: 960px;
+        margin: 0 auto;
+        padding: 3rem 1.5rem 4rem;
+        text-align: center;
+      }
+      .sdk-hero h1 {
+        font-size: 2.5rem;
+        margin-bottom: 0.5rem;
+      }
+      .sdk-hero p {
+        max-width: 600px;
+        margin: 0.5rem auto 2.5rem;
+        font-size: 1.05rem;
+        opacity: 0.9;
+      }
+      .sdk-grid {
+        display: flex;
+        flex-wrap: wrap;
+        justify-content: center;
+        gap: 1.75rem;
+      }
+      .sdk-card {
+        width: 320px;
+        padding: 2rem 1.75rem;
+        border-radius: 16px;
+        background: radial-gradient(circle at top left,rgb(33, 25, 67),#111827 55%);
+        border: 1px solid rgba(212, 207, 255,0.3);
+        box-shadow: 0 18px 40px rgba(0,0,0,0.5);
+        text-align: left;
+        transition: transform .2s ease, box-shadow .2s ease, border-color .2s ease;
+      }
+      .sdk-card:hover {
+        transform: translateY(-4px);
+        box-shadow: 0 24px 55px rgba(0,0,0,0.65);
+        border-color: rgba(212, 207, 255,0.8);
+      }
+      .sdk-icon {
+        font-size: 2.4rem;
+        margin-bottom: 0.75rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+      .sdk-card h2 {
+        margin: 0 0 0.5rem;
+        font-size: 1.35rem;
+        text-align: center;
+      }
+      .sdk-card p {
+        margin: 0 0 1.25rem;
+        font-size: 0.98rem;
+        line-height: 1.5;
+        opacity: 0.9;
+        text-align: center;
+      }
+      .sdk-badges {
+        margin-bottom: 1.25rem;
+        display: flex;
+        gap: 0.4rem;
+        flex-wrap: wrap;
+        justify-content: center;
+      }
+      .sdk-badge {
+        font-size: 0.7rem;
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+        padding: 0.15rem 0.55rem;
+        border-radius: 999px;
+        border: 1px solid rgba(212, 207, 255,0.7);
+        color: rgba(212, 207, 255,0.9);
+      }
+      .sdk-actions {
+        display: flex;
+        gap: 0.5rem;
+        flex-wrap: wrap;
+        flex-direction: column; /* stack vertically */
+        align-items: center;    /* center horizontally */
+      }
+      .sdk-btn {
+        border-radius: 999px;
+        padding: 0.5rem 1rem;
+        font-size: 0.9rem;
+        font-weight: 600;
+        text-decoration: none;
+        border: 1px solid transparent;
+        display: inline-flex;
+        align-items: center;
+        gap: 0.4rem;
+        cursor: pointer;
+        background: transparent;
+      }
+      .sdk-btn-primary {
+        background: linear-gradient(135deg,rgb(99, 9, 255),#6366f1);
+        color: #f9fafb;
+        border-color: rgba(248,250,252,0.05);
+      }
+      .sdk-btn-primary:hover {
+        filter: brightness(1.06);
+      }
+      .sdk-btn-secondary {
+        border-color: rgba(148,163,184,0.6);
+        color: #e5e7eb;
+      }
+      .sdk-btn-secondary:hover {
+        background: rgba(15,23,42,0.8);
+      }
+      .sdk-arrow {
+        font-size: 1.1rem;
+      }
+      .sdk-footer {
+        text-align: center;
+        padding: 0 1.5rem 2.5rem;
+        font-size: 0.95rem;
+        color: rgba(209,213,219,0.85);
+      }
+      .sdk-footer ul {
+        list-style: none;
+        padding: 0;
+        margin: 0.5rem 0 0;
+      }
+      .sdk-footer li {
+        margin: 0.25rem 0;
+      }
+      .sdk-top-logo {
+        width: 128px;
+        height: 128px;
+        display: inline-block;
+        margin-bottom: 0.75rem;
+      }
+      @media (max-width: 768px) {
+        .sdk-card {
+          width: 100%;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main class="sdk-hero">
+      <img src="/overrides/assets/img/logo.svg" alt="HUMAN Protocol Logo" class="sdk-top-logo" width="128" height="128" />
+      <h1>
+          HUMAN Protocol SDKs
+      </h1>
+      <p>
+        Choose your preferred language SDK to integrate with HUMAN Protocol.
+        Both SDKs expose the same core concepts, so you can build automation, 
+        dApps, and services in the stack you know best.
+      </p>
+
+      <div class="sdk-grid">
+        <!-- TypeScript card -->
+        <section class="sdk-card">
+          <div class="sdk-icon">
+            <img src="/overrides/assets/img/ts-logo.png" alt="TypeScript Logo" width="64" height="64" />
+          </div>
+          <div class="sdk-badges">
+            <span class="sdk-badge">TypeScript</span>
+            <span class="sdk-badge">Node.js</span>
+          </div>
+          <h2>TypeScript SDK</h2>
+          <p>
+            Type-safe SDK for web, dApps and backend services.
+          </p>
+          <div class="sdk-actions">
+            <a href="/ts/" class="sdk-btn sdk-btn-primary">
+              Go to TypeScript SDK <span class="sdk-arrow">↗</span>
+            </a>
+            <a href="https://www.npmjs.com/package/@human-protocol/sdk" class="sdk-btn sdk-btn-secondary">
+              View on npm
+            </a>
+          </div>
+        </section>
+
+        <!-- Python card -->
+        <section class="sdk-card">
+          <div class="sdk-icon">
+            <img src="/overrides/assets/img/python-logo.webp" alt="Python Logo" width="64" height="64" />
+          </div>
+          <div class="sdk-badges">
+            <span class="sdk-badge">Python</span>
+          </div>
+          <h2>Python SDK</h2>
+          <p>
+            Python SDK for automation, bots, data/ML pipelines, and backend services.
+          </p>
+          <div class="sdk-actions">
+            <a href="/python/" class="sdk-btn sdk-btn-primary">
+              Go to Python SDK <span class="sdk-arrow">↗</span>
+            </a>
+            <a href="https://pypi.org/project/human-protocol-sdk/" class="sdk-btn sdk-btn-secondary">
+              View on PyPI
+            </a>
+          </div>
+        </section>
+      </div>
+    </main>
+
+    <footer class="sdk-footer">
+      <a href="https://docs.humanprotocol.org" class="sdk-btn sdk-btn-primary" style="margin-top: 1rem;">
+        Visit HUMAN Protocol documentation <span class="sdk-arrow">↗</span>
+      </a>
+    </footer>
+  </body>
+</html>
diff --git a/docs/mkdocs-python.yaml b/docs/mkdocs-python.yaml
@@ -0,0 +1,98 @@
+site_name: HUMAN Protocol Python SDK Docs
+site_url: https://sdk.humanprotocol.org/python/
+repo_name: humanprotocol/human-protocol
+repo_url: https://github.com/humanprotocol/human-protocol
+docs_dir: ../packages/sdk/python/human-protocol-sdk/docs
+site_dir: python
+theme:
+  name: material
+  custom_dir: overrides
+  logo: assets/img/logo.svg
+  favicon: assets/img/logo.svg
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-3
+        name: Switch to light mode
+  font:
+    text: Noto Sans
+    code: Roboto Mono
+  features:
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.top
+    - navigation.tracking
+    - navigation.path
+    - navigation.indexes
+    - navigation.prune
+    - content.tabs
+    - content.code.copy
+    - toc.follow
+    - announce.dismiss
+extra:
+  language: python
+  version:
+    provider: mike
+  logo_href: https://sdk.humanprotocol.org
+markdown_extensions:
+  - toc:
+      baselevel: 1
+      permalink: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.magiclink
+  - attr_list
+  - md_in_html
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [../packages/sdk/python/human-protocol-sdk]
+          options:
+            docstring_style: google
+            show_source: false
+            separate_signature: true
+            merge_init_into_class: true
+            heading_level: 2
+  - mike
+  - section-index
+nav:
+  - Overview: index.md
+  - Encryption: 
+      - Encryption: encryption.md
+      - Encryption Utils: encryption_utils.md
+      - LegacyEncryption: legacy_encryption.md
+  - Escrow: 
+      - EscrowClient: escrow_client.md
+      - EscrowUtils: escrow_utils.md
+  - KVStore:
+      - KVStoreClient: kvstore_client.md
+      - KVStoreUtils: kvstore_utils.md
+  - Operator:
+      - OperatorUtils: operator_utils.md
+  - Staking: 
+      - StakingClient: staking_client.md
+      - StakingUtils: staking_utils.md
+  - Statistics:
+      - StatisticsUtils: statistics_utils.md
+  - Transaction: 
+      - TransactionUtils: transaction_utils.md
+  - Worker:
+      - WorkerUtils: worker_utils.md
+  - Core utilities: core.md
+extra_css:
+  - assets/css/custom.css
-Original file line number
+Diff line change
@@ Expand Up / @@ -55,3 +55,7 @@ cache @@
     # Ignore developer-only local files
     .local
+    docs/ts
+    docs/python