Unable to contribute to docs

[hwaseem04]

I wanted to contribute to the Docs with neat code snippets for Python APIs (Like snippets found in PyTorch/Jax docs). I followed the instruction in this page

But I am getting the below error:

Running Sphinx v5.0.2
[autosummary] generating autosummary for: cpp/ops.rst, dev/extensions.rst, examples/linear_regression.rst, examples/llama-inference.rst, examples/mlp.rst, index.rst, install.rst, python/_autosummary/mlx.core.Device.rst, python/_autosummary/mlx.core.Dtype.rst, python/_autosummary/mlx.core.Stream.rst, ..., python/nn/layers.rst, python/nn/losses.rst, python/ops.rst, python/optimizers.rst, python/random.rst, python/transforms.rst, python/tree_utils.rst, quick_start.rst, unified_memory.rst, using_streams.rst

Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x103d116c0> for event 'builder-inited' threw an exception (exception: no module named mlx.core.linalg)
make: *** [html] Error 2

Any idea of why mlx.core.linalg is missing in my installation?. I installed mlx by pip install mlx.

Versions

Mac OS: 13.4
Python: 3.12
mlx: 0.0.6
sphinx: 5.0.2
sphinx_book_theme: 1.1.0

[altaic]

mlx.core.linalg was just added (post 0.0.6, and there isn't a new release yet). Use the main git branch.

[hwaseem04]

I was using the main branch and not the gh-pages branch. Do you want me to build mlx from the source?

PS: I ran make html in main branch. But it was instructed to be done in gh-pages branch. And now it works after I switched to gh-pages branch. Thank you.

[altaic]

My bad for the wrong branch. Glad you figured it out 🚀

[hwaseem04]

I have a small doubt. Let's say I wanted to add snippets to the Array Python API of MLX. Which file should I modify in the docs/ directory so that it reflects in these pages

PS: I am new to Sphinx style documentation conventions

[awni]

The docs on that page are all autogenerated from the source code which builds the array bindings.

Also you should not need to use the gh-pages branch to build the docs. That's just for deploying the docs. They should build fine on main. But you do need to build from source as the docs track with main so if something is new in main (but not released to pypi) they docs might not build fully.

[awni]

Also the auto generated docs from C++ won't change unless you rebuild the source code (this can be a bit annoying), but if you are changing anything in the C++ you need to rebuild to get the updated docs.

[hwaseem04]

Also the auto generated docs from C++ won't change unless you rebuild the source code (this can be a bit annoying), but if you are changing anything in the C++ you need to rebuild to get the updated docs.

I think I need to be more clear. What I wanted to do in the docs part is that I wanted to make it more beginner-friendly, as in to include 'How to' syntaxes for the API calls. I saw a few tweets where people face issues (for instance - here) in how to use the API calls even know it is very similar to the Numpy syntax.

So essentially what I am currently aiming for is to provide Python snippet examples like in PyTorch/Jax documentation for each API call. I am not intending to change anything in C++ source code.

So how should I achieve it. Where should I include/write it?

[awni]

It's hard to give one answer to that question. But for example if you want to add an example to a core operation, you can do it in the C++ docstring directly. For example here is the docstring for squeeze

For NumPy interop, I think we should just have a separate section in the docs on that. I will actually add that section and then you can update it if you see anything missing.

[hwaseem04]

Hmm, so one way you are currently suggesting is to directly add code snippets as doc strings. I am not sure how it will look on the docs webpage.

The other suggestion is perfectly fine. Kindly update once you do that.

But don't you feel like having Python snippets as a part of the API page itself(some sort of basic explanation of how to use the API) for other functions in MLX? I feel this would help people who are getting started in MLX without the need to look at other external docs (for instance Numpy's) or navigate between pages.

I just wish to make MLX's doc similar to PyTorch.
What is your take on it?

[awni]

Hmm, so one way you are currently suggesting is to directly add code snippets as doc strings.

The docstrings get added into the documentation for the operation. See for example this docstring which includes examples on how to use the norm function.

[hwaseem04]

The docstrings get added into the documentation for the operation. See for example this docstring which includes examples of how to use the norm function.

Oh, this seems pretty clean. Then can I write similar examples for other APIs and make a PR?

[awni]

Exactly :)