Skip to content

Commit 4bebfec

Browse files
portuu3portuu3
authored
Use Mkdocs for sdk documents (#3721)
1 parent 58a4414 commit 4bebfec

233 files changed

Lines changed: 6207 additions & 20189 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/cd-gitbook-sdk-docs.yaml‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,7 @@ cache
5555

5656
# Ignore developer-only local files
5757
.local
58+
59+
60+
docs/ts
61+
docs/python

‎docs/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# SDK Docs workflow
2+
3+
## Prerequisites
4+
- `pip install -r docs/requirements.txt`
5+
- `yarn install`
6+
- `yarn build:libs`
7+
8+
## Local preview
9+
- TypeScript docs: `mkdocs serve -f docs/mkdocs-ts.yaml`
10+
- Python docs: `mkdocs serve -f docs/mkdocs-python.yaml`
11+
12+
## Deploying a new version (mike)
13+
- TypeScript:
14+
`yarn workspace @human-protocol/sdk build:doc`
15+
`mike deploy -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`
16+
`mike set-default -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`
17+
- Python:
18+
`mike deploy -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`
19+
`mike set-default -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`
20+
21+
## Deleting a deployed version
22+
- TypeScript: `mike delete -F ./docs/mkdocs-ts.yaml --deploy-prefix docs/ts [VERSION]`
23+
- Python: `mike delete -F ./docs/mkdocs-python.yaml --deploy-prefix docs/python [VERSION]`
24+
25+
## Landing page (docs/index.html)
26+
- If you edit `docs/index.html`, apply the change both on your working branch and on `gh-pages`.
27+
28+
NEVER MERGE THE BRANCHES: `gh-pages` only contains docs builds, not the monorepo code.
29+
30+
## Serving static files
31+
- Serve only `index.html` (SDK docs won’t load): from `docs/`, run
32+
`python -m http.server 8080 --bind 127.0.0.1`
33+
- Serve the full published docs: create a mike deployment, switch to the `gh-pages` branch, go to `docs/`, then run
34+
`python -m http.server 8080 --bind 127.0.0.1`
35+
36+
## Repository structure (docs)
37+
- `docs/index.html`: Static landing page that links to SDK docs (TS/Python).
38+
- `docs/mkdocs-ts.yaml`: MkDocs config for the TypeScript site (deploys under `docs/ts` via mike).
39+
- `docs/mkdocs-python.yaml`: MkDocs config for the Python site (deploys under `docs/python` via mike).
40+
- `docs/ts/`: TypeScript site output; versioned builds live under `docs/ts/<version>` with per-version assets in `docs/ts/<version>/assets/`.
41+
- `docs/python/`: Python site output (if published); versioned builds live under `docs/python/<version>`.
42+
- `docs/overrides/`: Shared MkDocs theme overrides and assets (logo/header partials and images).

‎docs/index.html‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<title>HUMAN Protocol SDKs</title>
6+
<meta name="viewport" content="width=device-width, initial-scale=1" />
7+
<style>
8+
body {
9+
font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
10+
margin: 0;
11+
padding: 0;
12+
background: #050319;
13+
color: #f6f3ff;
14+
}
15+
.sdk-hero {
16+
max-width: 960px;
17+
margin: 0 auto;
18+
padding: 3rem 1.5rem 4rem;
19+
text-align: center;
20+
}
21+
.sdk-hero h1 {
22+
font-size: 2.5rem;
23+
margin-bottom: 0.5rem;
24+
}
25+
.sdk-hero p {
26+
max-width: 600px;
27+
margin: 0.5rem auto 2.5rem;
28+
font-size: 1.05rem;
29+
opacity: 0.9;
30+
}
31+
.sdk-grid {
32+
display: flex;
33+
flex-wrap: wrap;
34+
justify-content: center;
35+
gap: 1.75rem;
36+
}
37+
.sdk-card {
38+
width: 320px;
39+
padding: 2rem 1.75rem;
40+
border-radius: 16px;
41+
background: radial-gradient(circle at top left,rgb(33, 25, 67),#111827 55%);
42+
border: 1px solid rgba(212, 207, 255,0.3);
43+
box-shadow: 0 18px 40px rgba(0,0,0,0.5);
44+
text-align: left;
45+
transition: transform .2s ease, box-shadow .2s ease, border-color .2s ease;
46+
}
47+
.sdk-card:hover {
48+
transform: translateY(-4px);
49+
box-shadow: 0 24px 55px rgba(0,0,0,0.65);
50+
border-color: rgba(212, 207, 255,0.8);
51+
}
52+
.sdk-icon {
53+
font-size: 2.4rem;
54+
margin-bottom: 0.75rem;
55+
display: flex;
56+
align-items: center;
57+
justify-content: center;
58+
}
59+
.sdk-card h2 {
60+
margin: 0 0 0.5rem;
61+
font-size: 1.35rem;
62+
text-align: center;
63+
}
64+
.sdk-card p {
65+
margin: 0 0 1.25rem;
66+
font-size: 0.98rem;
67+
line-height: 1.5;
68+
opacity: 0.9;
69+
text-align: center;
70+
}
71+
.sdk-badges {
72+
margin-bottom: 1.25rem;
73+
display: flex;
74+
gap: 0.4rem;
75+
flex-wrap: wrap;
76+
justify-content: center;
77+
}
78+
.sdk-badge {
79+
font-size: 0.7rem;
80+
text-transform: uppercase;
81+
letter-spacing: 0.06em;
82+
padding: 0.15rem 0.55rem;
83+
border-radius: 999px;
84+
border: 1px solid rgba(212, 207, 255,0.7);
85+
color: rgba(212, 207, 255,0.9);
86+
}
87+
.sdk-actions {
88+
display: flex;
89+
gap: 0.5rem;
90+
flex-wrap: wrap;
91+
flex-direction: column; /* stack vertically */
92+
align-items: center; /* center horizontally */
93+
}
94+
.sdk-btn {
95+
border-radius: 999px;
96+
padding: 0.5rem 1rem;
97+
font-size: 0.9rem;
98+
font-weight: 600;
99+
text-decoration: none;
100+
border: 1px solid transparent;
101+
display: inline-flex;
102+
align-items: center;
103+
gap: 0.4rem;
104+
cursor: pointer;
105+
background: transparent;
106+
}
107+
.sdk-btn-primary {
108+
background: linear-gradient(135deg,rgb(99, 9, 255),#6366f1);
109+
color: #f9fafb;
110+
border-color: rgba(248,250,252,0.05);
111+
}
112+
.sdk-btn-primary:hover {
113+
filter: brightness(1.06);
114+
}
115+
.sdk-btn-secondary {
116+
border-color: rgba(148,163,184,0.6);
117+
color: #e5e7eb;
118+
}
119+
.sdk-btn-secondary:hover {
120+
background: rgba(15,23,42,0.8);
121+
}
122+
.sdk-arrow {
123+
font-size: 1.1rem;
124+
}
125+
.sdk-footer {
126+
text-align: center;
127+
padding: 0 1.5rem 2.5rem;
128+
font-size: 0.95rem;
129+
color: rgba(209,213,219,0.85);
130+
}
131+
.sdk-footer ul {
132+
list-style: none;
133+
padding: 0;
134+
margin: 0.5rem 0 0;
135+
}
136+
.sdk-footer li {
137+
margin: 0.25rem 0;
138+
}
139+
.sdk-top-logo {
140+
width: 128px;
141+
height: 128px;
142+
display: inline-block;
143+
margin-bottom: 0.75rem;
144+
}
145+
@media (max-width: 768px) {
146+
.sdk-card {
147+
width: 100%;
148+
}
149+
}
150+
</style>
151+
</head>
152+
<body>
153+
<main class="sdk-hero">
154+
<img src="/overrides/assets/img/logo.svg" alt="HUMAN Protocol Logo" class="sdk-top-logo" width="128" height="128" />
155+
<h1>
156+
HUMAN Protocol SDKs
157+
</h1>
158+
<p>
159+
Choose your preferred language SDK to integrate with HUMAN Protocol.
160+
Both SDKs expose the same core concepts, so you can build automation,
161+
dApps, and services in the stack you know best.
162+
</p>
163+
164+
<div class="sdk-grid">
165+
<!-- TypeScript card -->
166+
<section class="sdk-card">
167+
<div class="sdk-icon">
168+
<img src="/overrides/assets/img/ts-logo.png" alt="TypeScript Logo" width="64" height="64" />
169+
</div>
170+
<div class="sdk-badges">
171+
<span class="sdk-badge">TypeScript</span>
172+
<span class="sdk-badge">Node.js</span>
173+
</div>
174+
<h2>TypeScript SDK</h2>
175+
<p>
176+
Type-safe SDK for web, dApps and backend services.
177+
</p>
178+
<div class="sdk-actions">
179+
<a href="/ts/" class="sdk-btn sdk-btn-primary">
180+
Go to TypeScript SDK <span class="sdk-arrow">↗</span>
181+
</a>
182+
<a href="https://www.npmjs.com/package/@human-protocol/sdk" class="sdk-btn sdk-btn-secondary">
183+
View on npm
184+
</a>
185+
</div>
186+
</section>
187+
188+
<!-- Python card -->
189+
<section class="sdk-card">
190+
<div class="sdk-icon">
191+
<img src="/overrides/assets/img/python-logo.webp" alt="Python Logo" width="64" height="64" />
192+
</div>
193+
<div class="sdk-badges">
194+
<span class="sdk-badge">Python</span>
195+
</div>
196+
<h2>Python SDK</h2>
197+
<p>
198+
Python SDK for automation, bots, data/ML pipelines, and backend services.
199+
</p>
200+
<div class="sdk-actions">
201+
<a href="/python/" class="sdk-btn sdk-btn-primary">
202+
Go to Python SDK <span class="sdk-arrow">↗</span>
203+
</a>
204+
<a href="https://pypi.org/project/human-protocol-sdk/" class="sdk-btn sdk-btn-secondary">
205+
View on PyPI
206+
</a>
207+
</div>
208+
</section>
209+
</div>
210+
</main>
211+
212+
<footer class="sdk-footer">
213+
<a href="https://docs.humanprotocol.org" class="sdk-btn sdk-btn-primary" style="margin-top: 1rem;">
214+
Visit HUMAN Protocol documentation <span class="sdk-arrow">↗</span>
215+
</a>
216+
</footer>
217+
</body>
218+
</html>

‎docs/mkdocs-python.yaml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
site_name: HUMAN Protocol Python SDK Docs
2+
site_url: https://sdk.humanprotocol.org/python/
3+
repo_name: humanprotocol/human-protocol
4+
repo_url: https://github.com/humanprotocol/human-protocol
5+
docs_dir: ../packages/sdk/python/human-protocol-sdk/docs
6+
site_dir: python
7+
theme:
8+
name: material
9+
custom_dir: overrides
10+
logo: assets/img/logo.svg
11+
favicon: assets/img/logo.svg
12+
palette:
13+
- scheme: default
14+
primary: deep purple
15+
accent: purple
16+
toggle:
17+
icon: material/brightness-7
18+
name: Switch to dark mode
19+
- scheme: slate
20+
primary: deep purple
21+
accent: purple
22+
toggle:
23+
icon: material/brightness-3
24+
name: Switch to light mode
25+
font:
26+
text: Noto Sans
27+
code: Roboto Mono
28+
features:
29+
- navigation.instant
30+
- navigation.instant.prefetch
31+
- navigation.top
32+
- navigation.tracking
33+
- navigation.path
34+
- navigation.indexes
35+
- navigation.prune
36+
- content.tabs
37+
- content.code.copy
38+
- toc.follow
39+
- announce.dismiss
40+
extra:
41+
language: python
42+
version:
43+
provider: mike
44+
logo_href: https://sdk.humanprotocol.org
45+
markdown_extensions:
46+
- toc:
47+
baselevel: 1
48+
permalink: true
49+
- admonition
50+
- pymdownx.details
51+
- pymdownx.superfences
52+
- pymdownx.tabbed:
53+
alternate_style: true
54+
- pymdownx.highlight:
55+
anchor_linenums: true
56+
- pymdownx.magiclink
57+
- attr_list
58+
- md_in_html
59+
plugins:
60+
- search
61+
- mkdocstrings:
62+
handlers:
63+
python:
64+
paths: [../packages/sdk/python/human-protocol-sdk]
65+
options:
66+
docstring_style: google
67+
show_source: false
68+
separate_signature: true
69+
merge_init_into_class: true
70+
heading_level: 2
71+
- mike
72+
- section-index
73+
nav:
74+
- Overview: index.md
75+
- Encryption:
76+
- Encryption: encryption.md
77+
- Encryption Utils: encryption_utils.md
78+
- LegacyEncryption: legacy_encryption.md
79+
- Escrow:
80+
- EscrowClient: escrow_client.md
81+
- EscrowUtils: escrow_utils.md
82+
- KVStore:
83+
- KVStoreClient: kvstore_client.md
84+
- KVStoreUtils: kvstore_utils.md
85+
- Operator:
86+
- OperatorUtils: operator_utils.md
87+
- Staking:
88+
- StakingClient: staking_client.md
89+
- StakingUtils: staking_utils.md
90+
- Statistics:
91+
- StatisticsUtils: statistics_utils.md
92+
- Transaction:
93+
- TransactionUtils: transaction_utils.md
94+
- Worker:
95+
- WorkerUtils: worker_utils.md
96+
- Core utilities: core.md
97+
extra_css:
98+
- assets/css/custom.css

0 commit comments

Comments
 (0)