Why
Today src/mlx_benchmarks/ (envelope, publish, converters, system) has Python docstrings but no rendered API reference. Users have to read __init__.py to discover the public surface (e.g., get_converter(), ConverterContext, detect_system()).
Suggested approach
- Generate docs with
pdoc or sphinx-autodoc (whichever is smaller).
- Publish to GitHub Pages or fold into
docs/ so it links from README.
- Cover the public surface only:
mlx_benchmarks.envelope, mlx_benchmarks.publish, mlx_benchmarks.converters, mlx_benchmarks.system. Skip cli and logging_config.
- Add a
docs: workflow that runs on main and surfaces the build.
Acceptance
- README links to a hosted API reference.
- The reference shows class/function signatures with docstrings rendered.
mlx-bench-publish and get_converter() are findable without grepping source.
Filed as follow-up to the docs(presentation): polish work in #49.
Why
Today
src/mlx_benchmarks/(envelope, publish, converters, system) has Python docstrings but no rendered API reference. Users have to read__init__.pyto discover the public surface (e.g.,get_converter(),ConverterContext,detect_system()).Suggested approach
pdocorsphinx-autodoc(whichever is smaller).docs/so it links from README.mlx_benchmarks.envelope,mlx_benchmarks.publish,mlx_benchmarks.converters,mlx_benchmarks.system. Skipcliandlogging_config.docs:workflow that runs onmainand surfaces the build.Acceptance
mlx-bench-publishandget_converter()are findable without grepping source.Filed as follow-up to the
docs(presentation):polish work in #49.