diff --git a/docs/_static/custom.css b/docs/_static/custom.css index bac04989..c712f02d 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -10,3 +10,17 @@ body { html { scroll-behavior: auto; } + +/* Make checkboxes from the tasklist extension ('- [ ]' in Markdown) not add bullet points to the checkboxes. + +This can be removed once https://github.com/executablebooks/mdit-py-plugins/issues/59 is addressed. +*/ + +.contains-task-list { + list-style: none; +} + +/* Make the checkboxes indented like they are bullets */ +.task-list-item-checkbox { + margin: 0 0.2em 0.25em -1.4em; +} diff --git a/docs/conf.py b/docs/conf.py index d8d5c2da..ac9e6dd7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,8 @@ templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -myst_enable_extensions = ["dollarmath", "linkify"] +myst_enable_extensions = ["dollarmath", "linkify", "tasklist"] +myst_enable_checkboxes = True napoleon_use_rtype = False napoleon_use_param = False diff --git a/docs/dev/implementation-notes.md b/docs/dev/implementation-notes.md index 48fb01f1..7f9c4634 100644 --- a/docs/dev/implementation-notes.md +++ b/docs/dev/implementation-notes.md @@ -47,3 +47,17 @@ identical PyTorch uses a similar layout in `array_api_compat/torch/`, but it differs enough from NumPy/CuPy that very few common wrappers for those libraries are reused. Dask is close to NumPy in behavior and so most Dask functions also reuse the NumPy/CuPy common wrappers. + +Occasionally, a wrapper implementation will need to reference another wrapper +implementation, rather than the base `xp` version. The easiest way to do this +is to call `array_namespace`, like + +```py +wrapped_xp = array_namespace(x) +wrapped_xp.wrapped_func(...) +``` + +Also, if there is a very minor difference required for wrapping, say, CuPy and +NumPy, they can still use a common implementation in `common/_aliases.py` and +use the `is_*_namespace()` or `is_*_function()` [helper +functions](../helper-functions.rst) to branch as necessary. diff --git a/docs/dev/releasing.md b/docs/dev/releasing.md index b2236597..1ee17709 100644 --- a/docs/dev/releasing.md +++ b/docs/dev/releasing.md @@ -1,59 +1,108 @@ # Releasing -To release, first make sure that all CI tests are passing on `main`. +- [ ] **Create a PR with a release branch** -Note that CuPy must be tested manually (it isn't tested on CI). Use the script + This makes it easy to verify that CI is passing, and also gives you a place + to push up updates to the changelog and any last minute fixes for the + release. -``` -./test_cupy.sh -``` +- [ ] **Double check the release branch is fully merged with `main`.** -on a machine with a CUDA GPU. + (e.g., if the release branch is called `release`) -Once you are ready to release, create a PR with a release branch, so that you -can verify that CI is passing. You must edit + ``` + git checkout main + git pull + git checkout release + git merge main + ``` -``` -array_api_compat/__init__.py -``` +- [ ] **Make sure that all CI tests are passing.** -and update the version (the version is not computed from the tag because that -would break vendorability). You should also edit + Note that the GitHub action that publishes to PyPI does not check if CI is + passing before publishing. So you need to check this manually. -``` -docs/changelog.md -``` + This does mean you can ignore CI failures, but ideally you should fix any + failures or update the `*-xfails.txt` files before tagging, so that CI and + the CuPy tests fully pass. Otherwise it will be hard to tell what things are + breaking in the future. It's also a good idea to remove any xpasses from + those files (but be aware that some xfails are from flaky failures, so + unless you know the underlying issue has been fixed, an xpass test is + probably still xfail). -with the changes for the release. +- [ ] **Test CuPy.** -Once everything is ready, create a tag + CuPy must be tested manually (it isn't tested on CI, see + https://github.com/data-apis/array-api-compat/issues/197). Use the script -``` -git tag -a -``` + ``` + ./test_cupy.sh + ``` -(note the tag names are not prefixed, for instance, the tag for version 1.5 is -just `1.5`) + on a machine with a CUDA GPU. -and push it to GitHub -``` -git push origin -``` +- [ ] **Update the version.** -Check that the `publish distributions` action on the tag build works. Note -that this action will run even if the other CI fails, so you must make sure -that CI is passing *before* tagging. + You must edit -This does mean you can ignore CI failures, but ideally you should fix any -failures or update the `*-xfails.txt` files before tagging, so that CI and the -cupy tests pass. Otherwise it will be hard to tell what things are breaking in -the future. It's also a good idea to remove any xpasses from those files (but -be aware that some xfails are from flaky failures, so unless you know the -underlying issue has been fixed, an xpass test is probably still xfail). + ``` + array_api_compat/__init__.py + ``` -If the publish action fails for some reason and didn't upload the release to -PyPI, you will need to delete the tag and try again. + and update the version (the version is not computed from the tag because + that would break vendorability). -After the PyPI package is published, the conda-forge bot should update the -feedstock automatically. +- [ ] **Update the [changelog](../changelog.md).** + + Edit + + ``` + docs/changelog.md + ``` + + with the changes for the release. + +- [ ] **Create the release tag.** + + Once everything is ready, create a tag + + ``` + git tag -a + ``` + + (note the tag names are not prefixed, for instance, the tag for version 1.5 is + just `1.5`) + +- [ ] **Push the tag to GitHub.** + + *This is the final step. Doing this will build and publish the release!* + + ``` + git push origin + ``` + + This will trigger the [`publish + distributions`](https://github.com/data-apis/array-api-compat/actions/workflows/publish-package.yml) + GitHub Action that will build the release and push it to PyPI. + +- [ ] **Check that the [`publish + distributions`](https://github.com/data-apis/array-api-compat/actions/workflows/publish-package.yml) + action build on the tag worked.** Note that this action will run even if the + other CI fails, so you must make sure that CI is passing *before* tagging. + + If it failed for some reason, you may need to delete the tag and try again. + +- [ ] **Merge the release branch.** + + This way any changes you made in the branch, such as updates to the + changelog or xfails files, are updated in `main`. This will also make the + docs update (the docs are published automatically from the sources on + `main`). + +- [ ] **Update conda-forge.** + + After the PyPI package is published, the conda-forge bot should update the + feedstock automatically after some time. The bot should automerge, so in + most cases you don't need to do anything here, unless some metadata on the + feedstock needs to be updated.