type annotations make docs confusing

[dcherian]

The annotations make this signature basically unreadable to anyone not familiar with them.

Is there a way to hide them in the documentation? Or at least change formatting so it's clearer what the function arguments are?

[DocOtak]

Perhaps the sphinx-autodoc-typehints extension?

The docs suggest it will remove the types from the method signatures and put them in the in :param: parts. I haven't used or tested myself.

[dcherian]

Thanks @DocOtak. Are you interested in trying it out?

[DocOtak]

@dcherian sure, I'll try it right now with the xarray docs

[shoyer]

If we can't get that sphinx extension to work (I'm not sure if it will handle NumPy style docstrings), another option might to be define type aliases for the longer types, e.g., data_vars: DataVars. That would at least cut down on the noise.

[DocOtak]

So the plugin seems to "just works" in that it remove these data type annotation, it doesn't seem to put them anywhere. I can probably put the docs I built somewhere if you all want to look at them. Here is a screen shot of the "Dataset" class, first one is just the extension, second screenshot also has the napoleon extension enabled. Main difference is how the "parameters" appear.

[dcherian]

EDIT: ignore, I see you've tried napoleon

[dcherian]

Have you enabled napoleon_use_param? (https://stackoverflow.com/questions/49540656/how-to-automatically-add-parameter-types-in-sphinx-documentation)

Add 'sphinx_autodoc_typehints' to the extensions list in conf.py after 'sphinx.ext.napoleon', and make sure you also add napoleon_use_param = True to conf.py.

[DocOtak]

So I think why it isn't putting the types anywhere in the docs is because they already exist (at least for this Dataset __init__ that we are looking at).

The relevant part of the code in the extension appears to be this https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/sphinx_autodoc_typehints.py#L333:L338

It's looking for :param name: and I think things with types are already :param type name: with napoleon enabled, so it doesn't find anything to replace. Without napoleon enabled, the :param name: fields are not present since it is "raw" numpy doc style.

[DocOtak]

Suspicions confirmed. I removed the type parts in the docstrings. The attached is the result which I think is way less readable:

[shoyer]

I would be OK with stripping type hints entirely. Our long type annotations are mostly useful for tooling. The short annotations from our numpy-style docstrings are definitely more readable for humans.

[dcherian]

+1 I like the style with Napoleon enabled. It even fixes #3056.

[shoyer]

Yes, this is great! Please send a PR when you're ready :)

[DocOtak]

So I made a PR for just removing the type annotations, turns out it is built in to autodoc. Enabling napoleon seems to be less "clean". While it doesn't actually conflict with numpydoc it does appear to "compete" with it. It only really seemed to affect the autowrapped ufunc documentation. I'm going to do a separate "enable napoleon" PR