Skip to content

M23: public documentation & examples review - #38

Merged
ausimian merged 1 commit into
mainfrom
m23-docs-review
Apr 18, 2026
Merged

M23: public documentation & examples review#38
ausimian merged 1 commit into
mainfrom
m23-docs-review

Conversation

@ausimian

Copy link
Copy Markdown
Owner

Summary

Pre-1.0 pass over the documentation surface users consume on HexDocs. No behavioural changes.

  • Moduledoc pass. Added Public API sections to Emily, Emily.Backend, and Emily.Compiler distinguishing user-facing helpers from Nx.Backend / Nx.Defn.Compiler callback implementations. Added iex> examples to Emily.to_binary/1, shape/1, dtype/1, 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.
  • Zero-copy documentation. Emily.to_binary/1 now documents the buffer-refcount mechanism that blocks MLX's donation path and flags the BEAM ProcBin accounting footgun with three mitigations.
  • HexDocs nav. mix.exs groups extras into README and Notebooks; modules into Core / Concurrency / Quantization / Training / Performance / Observability.
  • README rewrite. Overview + Features bullets; Prerequisites section with the xcodebuild -downloadComponent MetalToolchain step; 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.
  • Runnable Livebooks. notebooks/distilbert_qa.livemd (Bumblebee QA through Emily.Compiler) and notebooks/qwen3_quantized.livemd (Qwen3-0.6B int4-quantized + Emily.Stream concurrent serving), both self-contained via Mix.install/2.
  • CHANGELOG cutover. Moved the M0–M22 release history from RELEASE.md into CHANGELOG.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.md carries only M23 notes.
  • mix docs runs 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)
  • End-to-end build from a fresh clone in /tmp (git clone --recurse-submodulesmix deps.getmix compile) with EMILY_CACHE overridden to force a cold MLX rebuild (cmake + Metal). README Usage example against the cold-built artefact produces [17.0, 39.0].

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).
@ausimian
ausimian merged commit 9b35d4d into main Apr 18, 2026
1 check passed
@ausimian
ausimian deleted the m23-docs-review branch April 18, 2026 08:16
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