Skip to content

Commit 8ed4beb

Browse files
author
OutBot CI
committed
docs: add MkDocs site with llms.txt support
1 parent c079fa0 commit 8ed4beb

30 files changed

+4457
-99
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# GitHub Actions workflow for MkDocs documentation
2+
# Builds docs, validates llms.txt generation, and deploys to GitHub Pages
3+
4+
name: Documentation
5+
6+
on:
7+
push:
8+
branches: [main]
9+
paths:
10+
- 'docs/**'
11+
- 'mkdocs.yml'
12+
- '.github/workflows/docs.yml'
13+
pull_request:
14+
branches: [main]
15+
paths:
16+
- 'docs/**'
17+
- 'mkdocs.yml'
18+
workflow_dispatch:
19+
20+
permissions:
21+
contents: read
22+
pages: write
23+
id-token: write
24+
25+
concurrency:
26+
group: "pages"
27+
cancel-in-progress: false
28+
29+
jobs:
30+
build:
31+
runs-on: ubuntu-latest
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v4
35+
36+
- name: Setup Python
37+
uses: actions/setup-python@v5
38+
with:
39+
python-version: '3.13'
40+
41+
- name: Install dependencies
42+
run: pip install -r docs/requirements.txt
43+
44+
- name: Build MkDocs (strict mode)
45+
run: mkdocs build --strict --verbose
46+
47+
- name: Verify llms.txt generated
48+
run: |
49+
if [ -f site/llms.txt ]; then
50+
echo "llms.txt generated successfully"
51+
head -50 site/llms.txt
52+
else
53+
echo "Warning: llms.txt not found"
54+
fi
55+
56+
- name: Verify llms-full.txt generated
57+
run: |
58+
if [ -f site/llms-full.txt ]; then
59+
echo "llms-full.txt generated successfully"
60+
wc -l site/llms-full.txt
61+
else
62+
echo "Warning: llms-full.txt not found"
63+
fi
64+
65+
- name: Upload artifact
66+
uses: actions/upload-pages-artifact@v3
67+
with:
68+
path: site/
69+
70+
deploy:
71+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
72+
environment:
73+
name: github-pages
74+
url: ${{ steps.deployment.outputs.page_url }}
75+
runs-on: ubuntu-latest
76+
needs: build
77+
steps:
78+
- name: Deploy to GitHub Pages
79+
id: deployment
80+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
.idea/
2+
.vscode/
3+
4+
# OS
5+
**/.DS_Store
6+
.DS_Store
7+
8+
# Build artifacts
9+
target/
10+
*.o
11+
*.tmp
12+
*.tmp_*
13+
14+
# Compiled binaries (from src/)
15+
/Combinators
16+
/Generators
17+
/Patterns
18+
/Properties
19+
/Reporters
20+
/Shrinkers
21+
/chapelcheck
22+
23+
# Example executables
24+
/examples/AlgebraicProperties
25+
/examples/CustomGenerators
26+
/examples/GettingStarted
27+
28+
# Test executables
29+
/tests/unit/GeneratorTests
30+
/tests/unit/PropertyTests
31+
/tests/unit/ShrinkerTests
32+
/tests/properties/SelfTests
33+
34+
# Docs (local Chapel docs)
35+
docs/chapel-2.6/
36+
37+
# Mason lock (decision: track it for reproducibility)
38+
# Mason.lock
39+
40+
# Local development configuration (keep local only)
41+
.claude/
42+
chplcheck.log
43+
.venv/
44+
site/

‎.gitlab-ci.yml‎

Lines changed: 24 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -167,113 +167,38 @@ docs:chpldoc:
167167
- docs/api/
168168
expire_in: 1 week
169169

170+
docs:mkdocs:
171+
stage: docs
172+
image: python:3.13-slim
173+
script:
174+
- pip install -r docs/requirements.txt
175+
- mkdocs build --strict --verbose
176+
- test -f site/llms.txt || echo "Warning: llms.txt not generated"
177+
- test -f site/llms-full.txt || echo "Warning: llms-full.txt not generated"
178+
artifacts:
179+
paths:
180+
- site/
181+
expire_in: 1 week
182+
183+
docs:linkcheck:
184+
stage: docs
185+
image: python:3.13-slim
186+
needs: ["docs:mkdocs"]
187+
script:
188+
- pip install linkchecker
189+
- linkchecker site/index.html --check-extern || true
190+
allow_failure: true
191+
170192
# ============================================
171193
# GitLab Pages - Documentation Hosting
172194
# ============================================
173195

174196
pages:
175197
stage: publish
176-
needs: ["docs:chpldoc"]
198+
needs: ["docs:mkdocs"]
177199
script:
178200
- mkdir -p public
179-
- cp -r docs/api/* public/ || echo "No API docs to copy"
180-
- |
181-
cat > public/index.html << 'HTMLEOF'
182-
<!DOCTYPE html>
183-
<html lang="en">
184-
<head>
185-
<meta charset="UTF-8">
186-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
187-
<title>quickchpl API Documentation</title>
188-
<style>
189-
:root { --bg: #1a1a2e; --fg: #eee; --accent: #7b68ee; --code-bg: #16213e; }
190-
* { box-sizing: border-box; margin: 0; padding: 0; }
191-
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
192-
background: var(--bg); color: var(--fg); line-height: 1.6; padding: 2rem; }
193-
.container { max-width: 960px; margin: 0 auto; }
194-
h1 { color: var(--accent); margin-bottom: 1rem; font-size: 2.5rem; }
195-
h2 { color: var(--accent); margin-top: 2rem; margin-bottom: 0.5rem; }
196-
p { margin-bottom: 1rem; }
197-
a { color: var(--accent); text-decoration: none; }
198-
a:hover { text-decoration: underline; }
199-
.badge { display: inline-block; background: var(--accent); color: white;
200-
padding: 0.25rem 0.5rem; border-radius: 4px; font-size: 0.75rem; margin: 0.25rem; }
201-
code { background: var(--code-bg); padding: 0.125rem 0.25rem; border-radius: 2px; }
202-
pre { background: var(--code-bg); padding: 1rem; border-radius: 4px;
203-
overflow-x: auto; margin: 1rem 0; }
204-
.modules { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
205-
gap: 1rem; margin: 2rem 0; }
206-
.module { background: var(--code-bg); padding: 1rem; border-radius: 8px;
207-
border: 1px solid var(--accent); }
208-
.module h3 { color: var(--accent); margin-bottom: 0.5rem; }
209-
</style>
210-
</head>
211-
<body>
212-
<div class="container">
213-
<h1>quickchpl</h1>
214-
<p>Property-Based Testing Framework for Chapel</p>
215-
<div>
216-
<span class="badge">Chapel 2.6+</span>
217-
<span class="badge">MIT License</span>
218-
<span class="badge">v1.0.0</span>
219-
</div>
220-
221-
<h2>Modules</h2>
222-
<div class="modules">
223-
<div class="module">
224-
<h3>Generators</h3>
225-
<p>Random value generators for testing</p>
226-
<a href="Generators.html">Documentation</a>
227-
</div>
228-
<div class="module">
229-
<h3>Properties</h3>
230-
<p>Property definition and execution</p>
231-
<a href="Properties.html">Documentation</a>
232-
</div>
233-
<div class="module">
234-
<h3>Shrinkers</h3>
235-
<p>Counterexample minimization</p>
236-
<a href="Shrinkers.html">Documentation</a>
237-
</div>
238-
<div class="module">
239-
<h3>Reporters</h3>
240-
<p>Test result formatting</p>
241-
<a href="Reporters.html">Documentation</a>
242-
</div>
243-
<div class="module">
244-
<h3>Combinators</h3>
245-
<p>Generator composition utilities</p>
246-
<a href="Combinators.html">Documentation</a>
247-
</div>
248-
<div class="module">
249-
<h3>Patterns</h3>
250-
<p>Common property patterns</p>
251-
<a href="Patterns.html">Documentation</a>
252-
</div>
253-
</div>
254-
255-
<h2>Quick Start</h2>
256-
<pre><code>use quickchpl;
257-
258-
// Define a property
259-
var prop = property("addition commutes",
260-
tupleGen(intGen(), intGen()),
261-
lambda((a, b): (int, int)) { return a + b == b + a; });
262-
263-
// Check the property
264-
var result = check(prop);
265-
assert(result.passed);</code></pre>
266-
267-
<h2>Links</h2>
268-
<p>
269-
<a href="https://github.com/Jesssullivan/quickchpl">GitHub Repository</a> |
270-
<a href="https://github.com/Jesssullivan/quickchpl/tree/main/examples">Examples</a> |
271-
<a href="https://github.com/Jesssullivan/quickchpl/blob/main/README.md">README</a>
272-
</p>
273-
</div>
274-
</body>
275-
</html>
276-
HTMLEOF
201+
- cp -r site/* public/
277202
artifacts:
278203
paths:
279204
- public

‎Containerfile‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Containerfile for quickchpl Documentation
2+
# Build: podman build -t quickchpl-docs -f Containerfile .
3+
# Run: podman run --rm -v $PWD:/workspace:Z quickchpl-docs
4+
5+
FROM python:3.13-slim AS base
6+
7+
# Create non-root user
8+
RUN useradd -m -s /bin/bash docs && \
9+
mkdir -p /workspace && \
10+
chown -R docs:docs /workspace
11+
12+
# Install UV for fast dependency management
13+
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
14+
15+
WORKDIR /workspace
16+
17+
# Install MkDocs dependencies
18+
COPY docs/requirements.txt /tmp/requirements.txt
19+
RUN uv pip install --system -r /tmp/requirements.txt
20+
21+
# Switch to non-root user
22+
USER docs
23+
24+
# Default command: build docs with strict validation
25+
CMD ["mkdocs", "build", "--strict"]
26+
27+
# Alternative commands:
28+
# Serve locally: podman run --rm -p 8000:8000 -v $PWD:/workspace:Z quickchpl-docs mkdocs serve -a 0.0.0.0:8000
29+
# Validate only: podman run --rm -v $PWD:/workspace:Z quickchpl-docs mkdocs build --strict --verbose

0 commit comments

Comments
 (0)