Skip to content

docs: add migration guide page #668

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.

Sign up for GitHub

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

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add migration guide page #668

wants to merge 2 commits into from

Conversation

steff456
Copy link
Member

fixes #658

This PR,

  • Adds a new migration page
  • Adds the new page under the Other heading at the top-level structure

The idea is to start growing the migration page with more examples from NumPy to the Array API Standard. @asmeurer I don't know if you have other examples in mind to add them in this PR.
@steff456 steff456 added the Narrative Content Narrative documentation content. label Jul 30, 2023
@steff456 steff456 added this to the v2023 milestone Jul 30, 2023
@steff456 steff456 requested review from asmeurer, rgommers and kgryte July 30, 2023 01:47
@steff456 steff456 self-assigned this Jul 30, 2023
steff456
steff456 commented Jul 30, 2023
View reviewed changes
spec/draft/migration_guide.md

The Array API Standard was based in the common APIs across multiple Python array libraries as a response to the fragmentation of the ecosystem. It was decided for the Array API Standard to be as compact as possible, meaning that it doesn't include all the creation and manipulation functions available in other libraries, but it is equally as powerful. The aim of this guide is to help users get started with the use of the Array API by providing common equivalents with the NumPy API.

Depending on the version of the Array API Standard that you are intended to use, the number of total APIs may vary and this migration guide is using the latest version `v2022.12`.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is important to mention what version this page is using, but I also fear this can starts to be a maintenance burden. So please let me know if it is just better to refer to the "latest version" or if it is ok to flag the actual version.
@asmeurer
Copy link
Member

This looks good. My idea was indeed to have a table, like a Rosetta stone (e.g., like https://github.com/sympy/sympy/wiki/Git-hg-rosetta-stone).

I would add two notes to the text at the top:

  • Some functions aren't easy to translate. In that case, if they are important, people should check if they are discussed already at https://github.com/data-apis/array-api/issues and request them if not. Also point out that people may have to use library-specific code paths for certain things that aren't in the standard yet.

  • Note that people should feel free to contribute to the page.

I can see about adding a few things myself once this is merged.
@asmeurer asmeurer mentioned this pull request Oct 11, 2023
Closed
@rgommers rgommers mentioned this pull request Jan 21, 2024
Closed
@kgryte kgryte modified the milestones: v2023, v2024 Jan 25, 2024
@kgryte kgryte modified the milestones: v2024, v2025 Dec 12, 2024
@kgryte kgryte changed the title Add migration guide page docs: add migration guide page Dec 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Narrative Content Narrative documentation content.
3 participants
@steff456 @asmeurer @kgryte