A mechanism for propagating docstring updates?

[leofang]

It's midnight so I might be asking silly or trivial questions...Let me know if I am! 😄

I think as we move forward and finalize the standard while downstream libraries start to implement the support, an apparent burden is to add docstings to all Array APIs. We certainly do not want to manually copy and paste all the docstrings from the standard, but rather we would rely on some kind of tools (should be a simple script?) to parse it.

However, is there a better way already conceived on how to propagate docstring changes to downstream? For example, if we fix a few docstrings in this repo, is there a mechanism (hopefully automated) to propagate it to all stakeholder projects (and perhaps beyond) at once? Or does it require each project's maintainer to inspect and determine from the fix if an API behavior is changed and so requires some code change as well?

[rgommers]

Good question. @asmeurer is updating the test suite regularly and parses the API docs to ensure docs and tests stay in sync, so I assume that updating to the latest version of the test suite should catch most/all of the changes. Maybe it'd be a matter of running one CI job against main of https://github.com/data-apis/array-api-tests?

[asmeurer]

What info are you including in the docstrings? My script in the test suite parses the signatures and some additional metadata, but doesn't parse everything. I've argued in the past that it would be helpful to have the spec in a machine readable format #49.

[leofang]

Maybe it'd be a matter of running one CI job against main of https://github.com/data-apis/array-api-tests?

Sounds like a good idea to start with.

What info are you including in the docstrings?

The whole docstring. 1-to-1 copy, with library-specific stuff appended at the end (possibly starting with .. note::). This way the maintenance cost is close to zero.

I've argued in the past that it would be helpful to have the spec in a machine readable format #49.

It'd be cool to have, though I am not sure if it'd increase our maintenance cost (for this repo) or not.

[rgommers]

The whole docstring. 1-to-1 copy, with library-specific stuff appended at the end

This is kind of problematic with docstring parsing, e.g. numpydoc chokes on duplicate sections. Also not easy to insert examples that way, you have to create some generic one and then replace the library name.

I think it'd be good to make copying content as easy as possible though. We've accumulated some technical debt here; the API docs really should have been in reST.

[rgommers]

Should this issue remain open? The API docs are now in .py files for easy reuse.

[rgommers]

I'll close this - having it available as regular docstrings makes them programmatically accessible, that's about as good as we can or need to do here. Thanks all!