Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Remove dependency on sphinx_autodoc_typehints #20875

Merged
merged 1 commit into from
Apr 29, 2024

Conversation

jakevdp
Copy link
Collaborator

@jakevdp jakevdp commented Apr 22, 2024

sphinx_autodoc_typehints does not have any support for declaring type aliases (see tox-dev/sphinx-autodoc-typehints#132 and tox-dev/sphinx-autodoc-typehints#284). The only option is using their typehints_formatter config, which we probably shouldn't use because it breaks sphinx cacheing (see #20872)

The net result is that aliases like ArrayLike and DtypeLike are expanded into their full unions in our docs, which makes for a poor user experience. For example: here are the current jax.lax.argmin docs:

324624157-6fe8ed01-e958-46be-83a7-cb2f1031e53d

This PR removes the sphinx_autodoc_typehints extension, and instead uses sphinx's native typehint handlers; the result is this:
Screenshot 2024-04-23 at 12 07 19 PM

I have tried unsuccessfully to figure out how to make jax.typing.ArrayLike and jax.typing.DtypeLike link to their documentation page, but I think this is better than the current version.

@jakevdp jakevdp self-assigned this Apr 22, 2024
@jakevdp jakevdp marked this pull request as draft April 22, 2024 23:34
@jakevdp jakevdp marked this pull request as ready for review April 23, 2024 19:09
@jakevdp jakevdp requested a review from hawkinsp April 23, 2024 19:10
@jakevdp jakevdp added the pull ready Ready for copybara import and testing label Apr 23, 2024
@jakevdp jakevdp force-pushed the no-typehints branch 2 times, most recently from d091ee1 to 6a19b0f Compare April 23, 2024 19:34
setup.py Outdated Show resolved Hide resolved
@copybara-service copybara-service bot merged commit 52a0cfc into jax-ml:main Apr 29, 2024
11 of 13 checks passed
@jakevdp jakevdp deleted the no-typehints branch April 29, 2024 22:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation pull ready Ready for copybara import and testing
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants