docs: add a guide section to the scaladoc site - #50
Merged
Conversation
scala-cli auto-detects docs/ as the scaladoc siteroot, so adding docs/_docs/ pages + docs/sidebar.yml turns on the "Docs" tab alongside the API — no workflow change. Matches the layout used in made and alpaca. Pages: - index.md — a verbatim copy of README.md (rendered as the Docs landing) - getting-started, annotations, combinators, backends — guides written against the current API, every scala snippet compiles under -snippet-compiler:compile - benchmarks — the report, moved from docs/benchmarks.md; images moved to docs/_assets/images/benchmarks/ and the benchmark scripts updated to match README: the sbt/mill install blocks are marked `sc:nocompile` (they aren't valid Scala and would fail the snippet compiler now that index.md renders), and `import made.annotation.name` is corrected to `halotukozak.made.annotation.name`. Keep docs/_docs/index.md byte-identical to README.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TCfiQMwXigsoCeMcR3jXP6
The MiMa baseline is now a worktree of a commit that contains benchmark/ (everything since #47), so `scala-cli package "$RUNNER_TEMP/old-src"` picks up benchmark/gencodec (Scala 2.13) and fails to resolve its deps. Completes the --exclude benchmark rollout started in #47. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TCfiQMwXigsoCeMcR3jXP6
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.
What
Turns on a Docs section on the scaladoc site (
mcodec.halotukozak.com), alongside the existing API reference. Same layout as made and alpaca —scala-cliauto-detectsdocs/as the siteroot, so this isdocs/_docs/*.md+docs/sidebar.ymlwith no workflow change.Pages
README.md, rendered as the Docs landing@name,@transparent,@flatten,@defaultCase,@stringEnum,@transientDefault,@outOfOrder, with the exact wire shapes from the test suitetransform,transformed,nullable,makeLazy,create,forceTransientDefaultsInput/Outputmodel, the JSON backend, BSON/CBOR statusdocs/benchmarks.mdEvery
scalasnippet in the guides compiles under-snippet-compiler:compile(the flag already indocs.yaml). Prose was run through thestop-sloppass.Also in this PR
docs/assets/benchmarks/*.png→docs/_assets/images/benchmarks/(scaladoc asset convention);benchmark/scripts/{plot,aggregate}.pyupdated to write there.README.md: the sbt/mill install blocks are taggedsc:nocompile(not valid Scala — they'd fail the snippet compiler now thatindex.mdrenders), andimport made.annotation.name→import halotukozak.made.annotation.name(the short form doesn't exist).Note for maintainers
docs/_docs/index.mdmust stay byte-identical toREADME.md(diff README.md docs/_docs/index.md). Same manual-sync arrangement as made — no hook added.🤖 Generated with Claude Code
Also fixes an incomplete
--exclude benchmarkrollout from #47: the MiMa workflow's baseline package ($RUNNER_TEMP/old-src) now also excludesbenchmark/, since the baseline commit now contains the Scala 2.13benchmark/gencodecbuild.