Skip to content

Commit 27c723e

Browse files
nullhacknullhack
committed
feat(docs): add unified doc site with ghp-import publishing
- Add docs/index.html landing page linking to API, coverage, and test reports - Replace bloated inline Python doc-publish with ghp-import one-liner - doc-build now generates all three outputs (pdoc + pytest-cov + pytest-html) - Add ghp-import to dev dependencies - Fix .gitignore to track docs/index.html and docs/features/ while ignoring generated outputs - Add docs/features/{backlog,in-progress,completed}/ directory structure
1 parent 92ce633 commit 27c723e

File tree

7 files changed

+119
-14
lines changed

7 files changed

+119
-14
lines changed

‎.gitignore‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ __pycache__/
66
*.py[cod]
77
*$py.class
88

9-
# Remove html generated by documentation
10-
11-
docs
9+
# Generated documentation (built by task doc-build)
10+
docs/api/
11+
docs/coverage/
12+
docs/tests/
1213
mutants
1314

1415
# C extensions

‎docs/features/backlog/.gitkeep‎

Whitespace-only changes.

‎docs/features/completed/.gitkeep‎

Whitespace-only changes.

‎docs/features/in-progress/.gitkeep‎

Whitespace-only changes.

‎docs/index.html‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Project Documentation</title>
7+
<style>
8+
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
9+
body {
10+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
11+
background: #0d1117;
12+
color: #e6edf3;
13+
min-height: 100vh;
14+
display: flex;
15+
flex-direction: column;
16+
align-items: center;
17+
justify-content: center;
18+
padding: 2rem;
19+
}
20+
h1 { font-size: 2rem; margin-bottom: 0.5rem; }
21+
.subtitle { color: #8b949e; margin-bottom: 3rem; font-size: 1rem; }
22+
.grid {
23+
display: grid;
24+
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
25+
gap: 1.5rem;
26+
width: 100%;
27+
max-width: 720px;
28+
}
29+
a.card {
30+
display: block;
31+
background: #161b22;
32+
border: 1px solid #30363d;
33+
border-radius: 10px;
34+
padding: 2rem 1.5rem;
35+
text-decoration: none;
36+
color: inherit;
37+
transition: border-color 0.2s, transform 0.15s;
38+
}
39+
a.card:hover { border-color: #58a6ff; transform: translateY(-2px); }
40+
.card-icon { font-size: 2rem; margin-bottom: 0.75rem; }
41+
.card-title { font-size: 1.1rem; font-weight: 600; margin-bottom: 0.4rem; }
42+
.card-desc { font-size: 0.85rem; color: #8b949e; }
43+
footer { margin-top: 4rem; font-size: 0.8rem; color: #484f58; }
44+
</style>
45+
</head>
46+
<body>
47+
<h1>Documentation</h1>
48+
<p class="subtitle">Generated project documentation</p>
49+
<div class="grid">
50+
<a class="card" href="api/app.html">
51+
<div class="card-icon">📖</div>
52+
<div class="card-title">API Reference</div>
53+
<div class="card-desc">Auto-generated from source docstrings via pdoc</div>
54+
</a>
55+
<a class="card" href="coverage/index.html">
56+
<div class="card-icon">🧪</div>
57+
<div class="card-title">Coverage Report</div>
58+
<div class="card-desc">Line-by-line test coverage breakdown</div>
59+
</a>
60+
<a class="card" href="tests/report.html">
61+
<div class="card-icon">✅</div>
62+
<div class="card-title">Test Results</div>
63+
<div class="card-desc">Full pytest run results with pass/fail details</div>
64+
</a>
65+
</div>
66+
<footer>Built with pdoc · pytest-cov · pytest-html</footer>
67+
</body>
68+
</html>

‎pyproject.toml‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ dev = [
3030
"taskipy>=1.14.1",
3131
"hypothesis>=6.148.4",
3232
"pyright>=1.1.407",
33+
"ghp-import>=2.1.0",
3334
]
3435

3536
[tool.setuptools]
@@ -128,17 +129,17 @@ ruff-format = "ruff format ."
128129
ruff-format-check = "ruff format . --check"
129130
lint = "task ruff-check && task ruff-format"
130131
doc-serve = "pdoc ./app --host localhost --port 8080"
131-
doc-build = "pdoc ./app -o docs/api --search"
132-
doc-publish = """\
133-
task doc-build && \
134-
git checkout gh-pages 2>/dev/null || git checkout -b gh-pages && \
135-
git rm -rf . && \
136-
git clean -fd && \
137-
cp -r docs/api/. . && \
138-
git add -A && \
139-
git commit -m "Publish API documentation" && \
140-
git push origin gh-pages --force && \
141-
git checkout main"""
132+
doc-build = """\
133+
pdoc ./app -o docs/api --search && \
134+
pytest \
135+
--cov-config=pyproject.toml \
136+
--cov-report html:docs/coverage \
137+
--cov=app \
138+
--html=docs/tests/report.html \
139+
--self-contained-html \
140+
-q \
141+
"""
142+
doc-publish = "task doc-build && ghp-import -n -p -f docs"
142143
static-check = "pyright"
143144

144145
[dependency-groups]

‎uv.lock‎

Lines changed: 35 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)