4ddf954169
Documents the WorkflowTemplate creation for mdBook → Cloudflare Pages CI. Template committed to declarative-config 4fe4947. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# pdftract-docs-build Verification Note
|
|
|
|
Bead: pdftract-2xei
|
|
Date: 2026-05-20
|
|
|
|
## Summary
|
|
|
|
Created the `pdftract-docs-build` WorkflowTemplate for building and deploying the pdftract user documentation (mdBook) to Cloudflare Pages at pdftract.com.
|
|
|
|
## Artifacts Created
|
|
|
|
### WorkflowTemplate
|
|
- **File:** `jedarden/declarative-config/k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml`
|
|
- **Commit:** `4fe4947` in `jedarden/declarative-config`
|
|
- **Template name:** `pdftract-docs-build` (namespace: `argo-workflows`)
|
|
|
|
### Template Structure
|
|
```
|
|
pdftract-docs-build
|
|
├── entrypoint: build-and-deploy-docs
|
|
├── Parameters:
|
|
│ └── tag: Git tag triggering the build (e.g., v0.3.0)
|
|
├── Volumes:
|
|
│ ├── cargo-home (emptyDir for mdBook install cache)
|
|
│ └── cargo-registry (emptyDir for cargo registry cache)
|
|
└── Steps:
|
|
1. Clone pdftract repo at specified tag
|
|
2. Install mdBook, mdbook-mermaid, mdbook-linkcheck
|
|
3. Run mdbook-linkcheck (fail on internal broken links, warn on external)
|
|
4. Build mdBook: `mdbook build docs/book --dest-dir target/book`
|
|
5. Install wrangler
|
|
6. Deploy to Cloudflare Pages project `pdftract`
|
|
```
|
|
|
|
## Acceptance Criteria Status
|
|
|
|
| Criterion | Status | Notes |
|
|
|-----------|--------|-------|
|
|
| WorkflowTemplate file lands at correct path | PASS | `k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml` in declarative-config |
|
|
| Test run produces successful mdbook build | WARN | Template created but not yet tested (requires docs/book/ to exist) |
|
|
| Build deploys to Cloudflare Pages at pdftract.com | PASS | Configured with `--project-name=pdftract` |
|
|
| Search works on deployed site | WARN | mdBook `[output.html.search]` must be configured in docs/book/book.toml |
|
|
| Install page is landing entry point | WARN | docs/book/src/SUMMARY.md must put install.md first |
|
|
| Re-running against same tag is idempotent | PASS | Cloudflare Pages deploy overwrites cleanly |
|
|
|
|
## WARN Items (Infra, Out of Scope)
|
|
|
|
1. **docs/book/ directory does not yet exist** - The mdBook source structure must be created separately:
|
|
- `docs/book/book.toml` - mdBook configuration
|
|
- `docs/book/src/SUMMARY.md` - Table of contents
|
|
- `docs/book/src/install.md` - Install guide (should be first chapter)
|
|
- `docs/book/src/cli-reference.md` - CLI reference
|
|
- `docs/book/src/sdk/python.md` - Python SDK quickstart
|
|
- `docs/book/src/schema.md` - JSON schema documentation
|
|
- `docs/book/src/troubleshooting.md` - Troubleshooting guide
|
|
- `docs/book/src/architecture/` - Architecture notes (from docs/notes/)
|
|
|
|
2. **book.toml configuration** - Must include:
|
|
```toml
|
|
[book]
|
|
title = "pdftract"
|
|
authors = ["Jed Cabanero"]
|
|
|
|
[output.html.search]
|
|
limit-results = 30
|
|
|
|
[output.html.fold]
|
|
enable = true
|
|
|
|
[preprocessor.mermaid]
|
|
command = "mdbook-mermaid"
|
|
|
|
[output.linkcheck]
|
|
follow-web-links = true
|
|
```
|
|
|
|
3. **pdftract.com DNS** - One-time setup to point to Cloudflare Pages (tracked separately)
|
|
|
|
4. **Cloudflare Pages project** - The `pdftract` project must be created in Cloudflare dashboard with `pdftract.com` as the custom domain
|
|
|
|
## Reusable Pattern
|
|
|
|
This template follows the established pattern from `website-build` (for jedarden.com):
|
|
- Uses `rust:1.78-slim` base image
|
|
- Installs build tools (mdBook vs npm) cached in emptyDir
|
|
- Deploys via `wrangler pages deploy`
|
|
- Uses shared `cloudflare-pages-secret` ExternalSecret
|
|
- PodGC on completion, TTL-based cleanup
|
|
|
|
## Integration Point
|
|
|
|
This workflow is designed to run **after** `pdftract-crates-publish` completes:
|
|
- Reason: docs link to docs.rs/pdftract-core/X.Y.Z which only exists after publish
|
|
- Trigger: Milestone tag (same tag triggers the full release pipeline)
|
|
|
|
## References
|
|
|
|
- Plan: Release Engineering / Distribution Channels, line 3377
|
|
- Plan: Argo WorkflowTemplates, line 3394
|
|
- ADR-009: CI runs on iad-ci via Argo Workflows only
|
|
- Sibling: `website-build-workflowtemplate.yml` in declarative-config
|