Skip to content

docs: docs-as-code documentation system for v0.9.1 - #15

Merged
ikelaiah merged 1 commit into
mainfrom
feat/doc-as-code-doc-system
Aug 23, 2026
Merged

ikelaiah merged 1 commit into
mainfrom
feat/doc-as-code-doc-system

Conversation

@ikelaiah

Copy link
Copy Markdown
Owner

Summary

Introduces a complete docs-as-code documentation system for ThreadPool-FP (still v0.9.1). Reuses the proven lightweight, dependency-free static-documentation architecture used by ChronoKit-FP and StringKit-FP and adapts it to ThreadPool-FP's own identity.

What it does

  • Curated information architecture (docs/layout.json + docs/versions.json): Getting Started, 12 Guides, Reference, and Internals navigation, with release notes / PR notes / archived plan / ADR kept as hidden-but-searchable pages.
  • Homepage with project-specific hero, 6 navigation cards, and the existing SVG banner.
  • Client-side search over titles, headings, prose, and API symbols (GlobalThreadPool, TSimpleThreadPool, IThreadPoolTask, SubmitRange, TryQueue, WaitForAll, Shutdown, ...), keyboard shortcut /.
  • Versioned output at /threadpool-fp/0.9.1/ with /threadpool-fp/ redirect, version selector, light/dark themes, theme selector, mobile nav, TOC, breadcrumbs, prev/next pagination, copy code blocks, offline ZIP + SHA-256.
  • Concurrency-accurate docs: guides/thread-safety.md and reference/contracts-and-limitations.md state exact guarantees (WaitForAll, cancellation, error containment, tombstones, deadlock guards, deadlines, backpressure) verified against source and the test suite.
  • Recipes = real code: 12 compiled programs under examples/documentation/ with expected-output files; code blocks in docs/guides/recipes.md are checked byte-identical to their source by tools/check_docs.py, and test_docs_examples.py compiles and runs them (FPC 3.2.2).
  • Validators + tests: build_docs.py, build_all_docs.py, check_docs.py, check_built_docs.py plus their test_*.py suites; the build fails on broken links, unsafe URLs, layout mismatches, or invalid metadata.
  • GitHub Pages automation: .github/workflows/documentation.yml (targeted on releases / workflow dispatch) builds, validates, and deploys via current actions/configure-pages + deploy-pages; CI gains a Documentation checks job and always compiles/run the recipe examples on Windows and Linux.
  • README / CONTRIBUTING / examples README link to the rendered site at https://ikelaiah.github.io/threadpool-fp/.

Verification

All green locally (expected to reproduce in CI):

  • test_build_docs / test_build_all_docs / test_check_built_docs / test_check_docs unit suites
  • check_docs.py + check_built_docs.py --site site
  • test_docs_examples.py — 12 programs compiled with FPC 3.2.2 and run against expected output
  • Full 36-page static site build + link/anchor/metadata validation

Manual step after merge

Enable Settings → Pages → Source = GitHub Actions so the provided workflow can publish.

Notes

  • Current release remains 0.9.1; only versions whose tag contains the documentation source tree are exposed (an earlier tag cannot honestly host the new layout).
  • Historical material (release notes, archived plan, PR notes, ADR) is preserved under docs/history/ and served as hidden, searchable pages — not primary navigation.

@ikelaiah
ikelaiah merged commit 17ad118 into main Aug 23, 2026
5 checks passed
@ikelaiah
ikelaiah deleted the feat/doc-as-code-doc-system branch August 23, 2026 10:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant