issue_comments

I tried using sphinx-autodoc-typehints in my own project but I'm getting a gazillion of errors. TypeVars don't work, Optional doesn't work, Literal doesn't work, intersphinx doesn't work (https://github.com/agronholm/sphinx-autodoc-typehints/issues/119), possibly more (the error log is just too long). :(

Any recollection as to if these ever worked as expected? Looks like between landing this change and doing the 0.14 release, the sphinx version bumped from 2.1.2 to 2.2.0 which included some changes to autodoc... This PR might be of interest https://github.com/sphinx-doc/sphinx/pull/6592 but it is not immediately obvious to me how/if this could have broken things.

Looks like this isn't fully fixed

See #3180 for the napoleon enabling PR.

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

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

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

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.

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

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.

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.

EDIT: ignore, I see you've tried napoleon

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.

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.

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

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

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.