Skip to content

Commit df11b76

Browse files
SirStigSirStig
committed
refactor: update documentation build process to use YOKEDCACHE_SITE_PATH_PREFIX for site path management and enhance CSS styles for improved visual consistency
1 parent 9f7b5fc commit df11b76

File tree

7 files changed

+179
-22
lines changed

7 files changed

+179
-22
lines changed

‎.devcontainer/dev.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ case "$1" in
9393
log_info "Building documentation..."
9494
activate_env
9595
pip install -q -e ".[docs]" 2>/dev/null || true
96-
python scripts/build_docs_site.py
96+
YOKEDCACHE_SITE_PATH_PREFIX= python scripts/build_docs_site.py
9797
cp CHANGELOG.md site/changelog.md 2>/dev/null || true
9898
python -m pdoc yokedcache -o site/api --template-directory site-src/pdoc-template
9999
log_success "Documentation built in site/"
@@ -103,7 +103,7 @@ case "$1" in
103103
log_info "Starting documentation server..."
104104
activate_env
105105
pip install -q -e ".[docs]" 2>/dev/null || true
106-
python scripts/build_docs_site.py
106+
YOKEDCACHE_SITE_PATH_PREFIX= python scripts/build_docs_site.py
107107
cp CHANGELOG.md site/changelog.md 2>/dev/null || true
108108
python -m pdoc yokedcache -o site/api --template-directory site-src/pdoc-template
109109
cd site && python -m http.server 58080 --bind 0.0.0.0

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ clean:
7878
# Documentation
7979
docs:
8080
python3 -m pip install -q -e ".[docs]"
81-
python3 scripts/build_docs_site.py
81+
YOKEDCACHE_SITE_PATH_PREFIX= python3 scripts/build_docs_site.py
8282
cp CHANGELOG.md site/changelog.md
8383
python3 -m pdoc yokedcache -o site/api --template-directory site-src/pdoc-template
8484
@echo "Output in site/ — run: cd site && python3 -m http.server 8000"

‎scripts/build_docs_site.py‎

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import shutil
99
import sys
1010
from pathlib import Path
11+
from urllib.parse import urlparse
1112

1213
import markdown
1314
from jinja2 import Environment, FileSystemLoader, select_autoescape
@@ -74,10 +75,19 @@ def md_to_html_path(md_rel: str) -> str:
7475
return Path(md_rel).with_suffix(".html").as_posix()
7576

7677

77-
def rel_href(from_page: str, to_page: str) -> str:
78-
a = Path(from_page).parent
79-
b = Path(to_page)
80-
return Path(os.path.relpath(b, a)).as_posix()
78+
def _link_path_segment() -> str:
79+
raw = os.environ.get("YOKEDCACHE_SITE_PATH_PREFIX")
80+
if raw is not None:
81+
return raw.strip().strip("/")
82+
return urlparse(SITE_URL).path.strip("/")
83+
84+
85+
def site_href(rel_path: str) -> str:
86+
rel = rel_path.strip().lstrip("/")
87+
seg = _link_path_segment()
88+
if seg:
89+
return f"/{seg}/{rel}"
90+
return f"/{rel}"
8191

8292

8393
def title_from_first_h1(body: str) -> str | None:
@@ -141,11 +151,11 @@ def nav_context(current_out: str) -> list[dict]:
141151
links = []
142152
for title, src in items:
143153
if src == "__api__":
144-
href = rel_href(current_out, "api/index.html")
154+
href = site_href("api/index.html")
145155
cur = current_out.startswith("api/")
146156
else:
147157
target = md_to_html_path(src)
148-
href = rel_href(current_out, target)
158+
href = site_href(target)
149159
cur = current_out == target
150160
links.append({"title": title, "href": href, "current": cur})
151161
groups.append({"label": label, "links": links})
@@ -215,9 +225,6 @@ def main() -> int:
215225
)
216226
canonical = f"{SITE_URL}/{out_rel}"
217227

218-
depth = len(Path(out_rel).parent.parts)
219-
ap = "../" * depth
220-
221228
html = tpl.render(
222229
title=title,
223230
description=desc,
@@ -226,11 +233,12 @@ def main() -> int:
226233
body_html=body_html,
227234
toc_html=toc_html,
228235
nav_groups=nav_context(out_rel),
229-
asset_prefix=ap,
230-
home_href=rel_href(out_rel, "index.html"),
231-
changelog_href=rel_href(out_rel, "changelog.html"),
232-
api_href=rel_href(out_rel, "api/index.html"),
233-
docs_first_href=rel_href(out_rel, "getting-started.html"),
236+
asset_style_href=site_href("assets/style.css"),
237+
asset_script_href=site_href("assets/app.js"),
238+
home_href=site_href("index.html"),
239+
changelog_href=site_href("changelog.html"),
240+
api_href=site_href("api/index.html"),
241+
docs_first_href=site_href("getting-started.html"),
234242
version=version,
235243
)
236244
out_path.write_text(html, encoding="utf-8")

‎site-src/pdoc-template/custom.css‎

Lines changed: 146 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
--yc-muted: #7e8fa5;
77
--yc-accent: #22d3ee;
88
--yc-border: rgba(255, 255, 255, 0.07);
9-
--yc-code: rgba(0, 0, 0, 0.38);
9+
--yc-code: rgba(0, 0, 0, 0.45);
10+
--yc-banner-bg: rgba(34, 211, 238, 0.08);
11+
--yc-banner-border: rgba(34, 211, 238, 0.22);
1012
}
1113

1214
@media (prefers-color-scheme: light) {
@@ -17,6 +19,18 @@
1719
--yc-accent: #0891b2;
1820
--yc-border: rgba(0, 0, 0, 0.08);
1921
--yc-code: rgba(0, 0, 0, 0.04);
22+
--yc-banner-bg: rgba(8, 145, 178, 0.08);
23+
--yc-banner-border: rgba(8, 145, 178, 0.2);
24+
}
25+
}
26+
27+
html {
28+
color-scheme: dark;
29+
}
30+
31+
@media (prefers-color-scheme: light) {
32+
html {
33+
color-scheme: light;
2034
}
2135
}
2236

@@ -43,9 +57,139 @@ pre {
4357

4458
.pdoc {
4559
--pdoc-background: var(--yc-bg);
60+
--text: var(--yc-text);
61+
--muted: var(--yc-muted);
62+
--link: var(--yc-accent);
63+
--link-hover: #5eead4;
64+
--link-hover: color-mix(in srgb, var(--yc-accent) 82%, white);
65+
--code: var(--yc-code);
66+
--active: rgba(34, 211, 238, 0.18);
67+
--accent: rgba(255, 255, 255, 0.05);
68+
--accent2: var(--yc-border);
69+
--nav-hover: rgba(255, 255, 255, 0.08);
70+
--name: #7dd3fc;
71+
--def: #86efac;
72+
--annotation: #c4b5fd;
73+
}
74+
75+
@media (prefers-color-scheme: light) {
76+
.pdoc {
77+
--link-hover: #0e7490;
78+
--link-hover: color-mix(in srgb, var(--yc-accent) 75%, black);
79+
--active: rgba(8, 145, 178, 0.16);
80+
--accent: rgba(0, 0, 0, 0.04);
81+
--nav-hover: rgba(0, 0, 0, 0.06);
82+
--name: #0369a1;
83+
--def: #15803d;
84+
--annotation: #5b21b6;
85+
}
4686
}
4787

4888
.pdoc-header,
49-
nav.pdoc-nav {
89+
nav.pdoc {
5090
border-color: var(--yc-border) !important;
5191
}
92+
93+
nav.pdoc li:hover {
94+
background-color: var(--nav-hover) !important;
95+
}
96+
97+
.yc-pdoc-banner {
98+
margin: 0;
99+
padding: 0.65rem 1rem 0.65rem calc(var(--sidebar-width, 14rem) + 1.5rem);
100+
font-size: 0.88rem;
101+
line-height: 1.45;
102+
color: var(--yc-text);
103+
background: var(--yc-banner-bg);
104+
border-bottom: 1px solid var(--yc-banner-border);
105+
}
106+
107+
.yc-pdoc-banner a {
108+
font-weight: 500;
109+
}
110+
111+
@media (max-width: 769px) {
112+
.yc-pdoc-banner {
113+
padding-left: 1rem;
114+
padding-right: 3rem;
115+
}
116+
}
117+
118+
.pdoc .pdoc-code {
119+
background: var(--yc-code) !important;
120+
color: var(--yc-text) !important;
121+
}
122+
123+
@media (prefers-color-scheme: dark) {
124+
.pdoc .pdoc-code .hll {
125+
background-color: rgba(250, 204, 21, 0.12);
126+
}
127+
.pdoc .pdoc-code .c,
128+
.pdoc .pdoc-code .ch,
129+
.pdoc .pdoc-code .cm,
130+
.pdoc .pdoc-code .cp,
131+
.pdoc .pdoc-code .cpf,
132+
.pdoc .pdoc-code .c1,
133+
.pdoc .pdoc-code .cs {
134+
color: #94a3b8 !important;
135+
}
136+
.pdoc .pdoc-code .k,
137+
.pdoc .pdoc-code .kc,
138+
.pdoc .pdoc-code .kd,
139+
.pdoc .pdoc-code .kn,
140+
.pdoc .pdoc-code .kr {
141+
color: #7dd3fc !important;
142+
}
143+
.pdoc .pdoc-code .kp {
144+
color: #a5f3fc !important;
145+
}
146+
.pdoc .pdoc-code .nf,
147+
.pdoc .pdoc-code .fm {
148+
color: #86efac !important;
149+
}
150+
.pdoc .pdoc-code .nc,
151+
.pdoc .pdoc-code .nn,
152+
.pdoc .pdoc-code .nb {
153+
color: #fde68a !important;
154+
}
155+
.pdoc .pdoc-code .s,
156+
.pdoc .pdoc-code .s1,
157+
.pdoc .pdoc-code .s2,
158+
.pdoc .pdoc-code .sa,
159+
.pdoc .pdoc-code .sb,
160+
.pdoc .pdoc-code .sc,
161+
.pdoc .pdoc-code .dl,
162+
.pdoc .pdoc-code .sd {
163+
color: #fca5a5 !important;
164+
}
165+
.pdoc .pdoc-code .mi,
166+
.pdoc .pdoc-code .mf,
167+
.pdoc .pdoc-code .mh,
168+
.pdoc .pdoc-code .mo,
169+
.pdoc .pdoc-code .mb {
170+
color: #fdba74 !important;
171+
}
172+
.pdoc .pdoc-code .o {
173+
color: #cbd5e1 !important;
174+
}
175+
.pdoc .pdoc-code .p {
176+
color: #cbd5e1 !important;
177+
}
178+
.pdoc .pdoc-code .nt {
179+
color: #7dd3fc !important;
180+
}
181+
.pdoc .pdoc-code .na {
182+
color: #a7f3d0 !important;
183+
}
184+
.pdoc .pdoc-code .nv,
185+
.pdoc .pdoc-code .vc,
186+
.pdoc .pdoc-code .vg,
187+
.pdoc .pdoc-code .vi,
188+
.pdoc .pdoc-code .vm {
189+
color: #c4b5fd !important;
190+
}
191+
.pdoc .pdoc-code .go,
192+
.pdoc .pdoc-code .w {
193+
color: #64748b !important;
194+
}
195+
}

‎site-src/pdoc-template/frame.html.jinja2‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% extends "default/frame.html.jinja2" %}
2+
{% block body %}
3+
<p class="yc-pdoc-banner">This section is the <strong>Python API reference</strong>: modules, classes, and functions, generated from source by <strong>pdoc</strong>. For guides and tutorials, see the <a href="../getting-started.html">documentation</a>.</p>
4+
{{ super() }}
5+
{% endblock %}

‎site-src/static/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ <h2>Documentation</h2>
152152
</tr>
153153
<tr>
154154
<td>Python API</td>
155-
<td><a href="api/index.html">Generated API docs (pdoc) →</a></td>
155+
<td><a href="api/index.html">API reference (pdoc: modules &amp; types from docstrings) →</a></td>
156156
</tr>
157157
<tr>
158158
<td>Releases</td>

‎site-src/templates/doc_page.html.jinja2‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
<link rel="preconnect" href="https://fonts.googleapis.com">
1212
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
1313
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
14-
<link rel="stylesheet" href="{{ asset_prefix }}assets/style.css">
14+
<link rel="stylesheet" href="{{ asset_style_href }}">
1515
<script type="application/ld+json">
1616
{
1717
"@context": "https://schema.org",
@@ -96,6 +96,6 @@
9696
</div>
9797

9898
<div class="sidebar-overlay" id="sidebarOverlay" aria-hidden="true"></div>
99-
<script src="{{ asset_prefix }}assets/app.js"></script>
99+
<script src="{{ asset_script_href }}"></script>
100100
</body>
101101
</html>

0 commit comments

Comments
 (0)