Update documentation

[asmeurer]

@rgommers if you have a chance, can you review this?

In addition to the changes in this PR, can you also take a look at the repo as a whole. I think I have everything ready to do an initial release, but I don't know if I forgot anything.

I also opened some issues on this repo for ideas of things we can do in the future. But I want to keep the first release as close to the current numpy.array_api as possible.

[rgommers]

In addition to the changes in this PR, can you also take a look at the repo as a whole. I think I have everything ready to do an initial release, but I don't know if I forgot anything.

I think it can be shipped as is, however you may want to do some of the following (can be done later):

• Packaging: we may want to be good citizens and use pyproject.toml here, and get rid of all setup.* content
• versioneer is pretty awful, and this package is really simple. I'd just use 1.0 and then 1.1-dev in pyproject.toml and leave it at that, rather than use thousands of lines of questionable-quality code to support a simple version string.

I also opened some issues on this repo for ideas of things we can do in the future. But I want to keep the first release as close to the current numpy.array_api as possible.

Good ideas, +1 to both the first release plan and all of those things as follow-ups.

[rgommers]

I'll give this a try with SciPy

[rgommers]

Looks like the switchover is easy and everything works as expected for SciPy.

[asmeurer]

I've used versioneer on dozens of projects and never had any issues with it. All the code in versioneer is used for generating development version numbers and doing packaging. The actual resulting package has a very simple file generated in it. Here's what it creates for this branch

# This file was generated by 'versioneer.py' (0.29) from
# revision-control system data, or from the parent directory name of an
# unpacked source archive. Distribution tarballs contain a pre-generated copy
# of this file.

import json

version_json = '''
{
 "date": "2024-01-23T17:55:23-0700",
 "dirty": false,
 "error": null,
 "full-revisionid": "c2d570061e8434b58c4e6609e2a849cf75e6a390",
 "version": "0+untagged.193.gc2d5700"
}
'''  # END VERSION_JSON

def get_versions():
    return json.loads(version_json)

Admittedly, even that is more complicated than it could be. It could just generate a file with just `version = ''. But it's way simpler for runtime than, e.g., setuptools_scm, which grabs the version number from the package metadata. I don't like that at all. If you know of a simpler tool I'm open to using it, but I do like to have something that lets me write the version number just once (in the tag). Otherwise I forget to update it, like I recently did for array-api-compat (we can't use versioneer there because of the vendorability requirement). I don't actually care as much about the git hash version thing, although it is nice to have and it occasionally helps with debugging user issues.

[rgommers]

If you know of a simpler tool I'm open to using it, but I do like to have something that lets me write the version number just once (in the tag).

Imho none of these tools are worth it, for a one-line change per release. versioneer specifically we've had problems with in NumPy, and since dropped - as did Matplotlib and others. If you've had to debug versioneer code just once, you notice it's 2000+ lines of bad code generating 500+ lines more code to then ship.

But okay, I don't have to make the updates here, so your call.

[asmeurer]

OK, I'm going to try to do a release. Based on my experience with array-api-compat, getting the auto-deploy to work the first time around can be a little annoying, so I may end up pushing a 1.0 tag to this repo multiple times.

[asmeurer]

OK, array-api-strict 1.0 has been released. Now I need to create a conda-forge package.

[rgommers]

Great, thanks!