M23: public documentation & examples review - #38
Merged
Merged
Conversation
Pre-1.0 pass over the documentation surface users consume on HexDocs.
- Moduledoc pass: added Public API sections to Emily, Emily.Backend,
and Emily.Compiler to distinguish user-facing helpers from
Nx.Backend / Nx.Defn.Compiler callback implementations. Added
iex> examples to Emily.{to_binary, shape, dtype}, Emily.Compiler,
Emily.Stream, Emily.Quantization, Emily.QuantizedWeight,
Emily.MixedPrecision, and Emily.Telemetry. Reorganised
Emily.Backend's divergences into a dedicated "Divergences from
Nx.BinaryBackend" subsection.
- Emily.to_binary/1 now documents the zero-copy semantics: the
pinned buffer refcount disqualifies MLX's donation path, and the
ProcBin accounting footgun is flagged with mitigations.
- HexDocs nav via mix.exs: extras now grouped into README and
Notebooks; modules grouped into Core / Concurrency /
Quantization / Training / Performance / Observability.
- README rewrite: Overview + Features bullets, Prerequisites with
the xcodebuild -downloadComponent MetalToolchain step, Building
with a "Why vendored?" subsection covering ml-explore/mlx#3348
and #3405, and an expanded Concurrency model section covering
the worker-thread dispatch architecture.
- Two runnable Livebooks under notebooks/: distilbert_qa.livemd
(Bumblebee QA through Emily.Compiler) and qwen3_quantized.livemd
(Qwen3-0.6B int4-quantized + Emily.Stream concurrent serving).
- CHANGELOG cutover: moved the M0-M22 release history from
RELEASE.md into CHANGELOG.md, then drastically simplified it to
a top-level feature summary under [0.1.0] - unreleased. Users
who want per-milestone detail can consult the git history.
RELEASE.md now carries only M23 notes.
- mix docs runs clean (zero warnings).
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.
Summary
Pre-1.0 pass over the documentation surface users consume on HexDocs. No behavioural changes.
Emily,Emily.Backend, andEmily.Compilerdistinguishing user-facing helpers fromNx.Backend/Nx.Defn.Compilercallback implementations. Addediex>examples toEmily.to_binary/1,shape/1,dtype/1,Emily.Compiler,Emily.Stream,Emily.Quantization,Emily.QuantizedWeight,Emily.MixedPrecision, andEmily.Telemetry. ReorganisedEmily.Backend's divergences into a dedicated "Divergences fromNx.BinaryBackend" subsection.Emily.to_binary/1now documents the buffer-refcount mechanism that blocks MLX's donation path and flags the BEAM ProcBin accounting footgun with three mitigations.mix.exsgroups extras intoREADMEandNotebooks; modules intoCore/Concurrency/Quantization/Training/Performance/Observability.xcodebuild -downloadComponent MetalToolchainstep; Building with a "Why vendored?" subsection covering Make CommandEncoder thread local ml-explore/mlx#3348 and #3405; expanded Concurrency model section covering the worker-thread architecture.notebooks/distilbert_qa.livemd(Bumblebee QA throughEmily.Compiler) andnotebooks/qwen3_quantized.livemd(Qwen3-0.6B int4-quantized +Emily.Streamconcurrent serving), both self-contained viaMix.install/2.RELEASE.mdintoCHANGELOG.md, then collapsed it to a top-level feature summary under[0.1.0] - unreleased. Per-milestone detail now lives in the git history.RELEASE.mdcarries only M23 notes.mix docsruns clean (zero warnings).Test plan
mix precommit(4 doctests, 76 properties, 421 tests, 0 failures)mix test --only conformance(17 passing)mix docs(zero warnings)/tmp(git clone --recurse-submodules→mix deps.get→mix compile) withEMILY_CACHEoverridden to force a cold MLX rebuild (cmake + Metal). README Usage example against the cold-built artefact produces[17.0, 39.0].