Comprehensive docstrings for all top-level exports

[d-v-b]

Very few of the top-level functions have doctrings. This is bad and we should fix it, either by writing good docstrings from scratch or dynamically copying docstrings from other functions where appropriate.

[jhamman]

Huh! Most of the top level API functions should have docstrings. We copy these from the asynchronous API:

zarr-python/src/zarr/api/synchronous.py

Lines 292 to 316 in 498cb78

	consolidate_metadata.__doc__ = async_api.copy.__doc__
	copy.__doc__ = async_api.copy.__doc__
	copy_all.__doc__ = async_api.copy_all.__doc__
	copy_store.__doc__ = async_api.copy_store.__doc__
	load.__doc__ = async_api.load.__doc__
	open.__doc__ = async_api.open.__doc__
	open_consolidated.__doc__ = async_api.open_consolidated.__doc__
	save.__doc__ = async_api.save.__doc__
	save_array.__doc__ = async_api.save_array.__doc__
	save_group.__doc__ = async_api.save_group.__doc__
	tree.__doc__ = async_api.tree.__doc__
	array.__doc__ = async_api.array.__doc__
	group.__doc__ = async_api.group.__doc__
	open_group.__doc__ = async_api.open_group.__doc__
	create.__doc__ = async_api.create.__doc__
	empty.__doc__ = async_api.empty.__doc__
	empty_like.__doc__ = async_api.empty_like.__doc__
	full.__doc__ = async_api.full.__doc__
	full_like.__doc__ = async_api.full_like.__doc__
	ones.__doc__ = async_api.ones.__doc__
	ones_like.__doc__ = async_api.ones_like.__doc__
	open_array.__doc__ = async_api.open_array.__doc__
	open_like.__doc__ = async_api.open_like.__doc__
	zeros.__doc__ = async_api.zeros.__doc__
	zeros_like.__doc__ = async_api.zeros_like.__doc__

But looking at the docs page, this doesn't seem to be working as expected. Let's definitely fix this.

[VjayRam]

Hey @d-v-b, I'm willing to contribute to this issue. Is it still open?

[jhamman]

The issue is still open. There is some question about why our auto-api sphinx plugin is not picking up our docstrings. @dstansby and I noticed this again today. Some exploration on the sphinx configuration side would be where I would start here.

[dstansby]

I think this is a drawback of using https://sphinx-autoapi.readthedocs.io/en/latest/ for automatically creating the API docs - because it never imports the code, it only knows about docstrings that are "hard coded" into the source files, not docstrings that are modified at import time.

[d-v-b]

should we copy + paste the docstrings then (and maybe add a test that ensures that these should-be-copied docstrings are in fact identical between the source function and the derived function?)

[dstansby]

copy/pasting identical docstrings doesn't seem like fun in terms of long term maintenance.

Couple of potential other options I can see:

• Wrap functions with functools.wraps, and maybe autoapi will pick up that the docstring should be copied across? If not, we could open an upstream issue for this, I think it would be reasonable for autoapi to do this.
• Use sphinx-automodapi instead
• Drop automatic api documentaiton, and document stuff more manually.

[d-v-b]

copy/pasting identical docstrings doesn't seem like fun in terms of long term maintenance.

Hm, I thought this would mostly be a one-time chore. If we have tests that enumerate over pairs of functions and ensure that their docstrings match, then the long term maintenance seems low? E.g., If someone modifies the docstring for func foo, but they fail to make the same changes to func foo_but_sync, then the tests would fails and they would do a 1-time copy + paste.

Another plus is that "use a real docstring" is the only solution that puts a real, accurate docstring in the static source code of the project, which should be our goal IMO.

[dstansby]

FWIW I tried the functools.wraps idea and it doesn't seem to work with autoapi.

👍 I see the benefits of having docstrings next to the code - as long as they're robustly tested to make sure they don't get out of sync.