feat(site): onboard docs-engine, publishing doc/ as the guide - #6
Merged
Merged
Conversation
ebb had no docs/ directory at all - unlike raylib-android (which had
full scaffolding, just disabled while the repo was private), this is
a from-scratch onboarding.
doc/evaluation.md, doc/conformance.md and doc/adr/001-fiber-affinity.md
are real, reader-oriented documentation, not internal notes - but they
are also load-bearing: test/ebb/conformance_test.clj hardcodes
"doc/divergences.edn" and "doc/conformance.md" as its gate, and nine
files under src/ebb/impl/ carry "See doc/conformance.md" comments.
Moving them would mean rewriting that gate and a dozen-plus source
comments. Instead docs/guide/{evaluation,conformance}.md and
docs/guide/adr/001-fiber-affinity.md are relative symlinks into doc/,
same pattern as awesome-jolt's guide/index.md -> README.md: doc/ stays
the one canonical path every test and source comment already points
at, and the site gets a window into it rather than a copy.
docs/guide/index.md is a new page, not a symlink - ebb's README is
already a GitHub-facing pitch (install, quick example, a four-line
differences summary), so the guide gets its own "why this exists"
overview that indexes the three real pages, matching glitter's own
README-vs-guide/index.md split.
Known gap, not fixed here: conformance.md's own prose links to
divergences.edn (the machine-readable half of the same registry).
That's an .edn file, not a doc page the engine renders, and publishing
it as a site asset would mean rewriting that link in the canonical
file the test suite reads verbatim - not worth doing to suit the
site's layout. That one link 404s on the published site specifically;
it's fine on GitHub, and the guide page's own prose says so and points
there instead.
.github/workflows/site.yml + docs/check-site.sh: build and publish via
the org's shared jlt-commons/ci-builds reusable workflow. The checks
include a byte-size floor on the two symlinked pages specifically,
since a stale/broken symlink would still let the build succeed - slurp
on a dangling link fails loud, but a symlink repointed at the wrong
file would not.
Verified locally against docs-engine v0.2.0: `bb build` succeeds,
docs/check-site.sh passes (index, guide overview, evaluation,
conformance and the ADR all present), and serving the build under
/ebb/ (not root) returns 200 for all 10 emitted URLs with nothing
escaping the base path. Confirmed the inherited cross-links between
evaluation.md/conformance.md/the ADR (written assuming doc/'s own
flat-plus-adr/ layout) correctly rewrite to .html at the same nesting
depth under docs/guide/, and confirmed the divergences.edn gap is
exactly that gap and nothing else (404, not a broader breakage).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ebb had no
docs/directory at all — unlike raylib-android (which had fullscaffolding, just disabled while the repo was private), this is a
from-scratch onboarding.
doc/evaluation.md,doc/conformance.mdanddoc/adr/001-fiber-affinity.mdare real, reader-oriented documentation — but they're also load-bearing:
test/ebb/conformance_test.cljhardcodes"doc/divergences.edn"and"doc/conformance.md"as its gate, and nine files undersrc/ebb/impl/carry
See doc/conformance.mdcomments. Moving them would mean rewritingthat gate and a dozen-plus source comments, so instead
docs/guide/{evaluation,conformance}.mdanddocs/guide/adr/001-fiber-affinity.mdare relative symlinks intodoc/— same pattern as awesome-jolt's
guide/index.md→README.md.doc/stays the one canonical path every test and source comment already points
at; the site gets a window into it, not a copy.
docs/guide/index.mdis a new page (not a symlink) — ebb's README isalready a GitHub-facing pitch, so the guide gets its own overview that
indexes the three real pages, matching glitter's README-vs-guide split.
Known gap, not fixed here
conformance.md's own prose links todivergences.edn(the machine-readablehalf of the same registry). That's an
.ednfile, not a doc page the enginerenders, and publishing it as a site asset would mean rewriting that link in
the canonical file the test suite reads verbatim — not worth doing just to
suit the site's layout. That one link 404s on the published site
specifically; it's fine on GitHub, and the guide page's own prose says so
and points there instead.
Verified locally
Against
docs-enginev0.2.0:bb buildsucceeds,docs/check-site.shpasses (index, guide overview,evaluation, conformance and the ADR all present).
/ebb/(not root) — all 10 emitted URLs return200, nothing escapes the base path, no unrendered
{{site-base}}.evaluation.md/conformance.md/the ADR (written assuming
doc/'s own flat-plus-adr/layout) correctlyrewrite to
.htmlat the same nesting depth underdocs/guide/.divergences.edngap is exactly that gap and nothing else(a clean 404, not a broader breakage).
Not done here
GitHub Pages has no site at all for this repo yet. Enabling it is its own
explicit step, done right before merge per the org's own migration runbook,
not bundled into this PR.