DOC: Better type hints

[adriangb]

#208 has some nice type hint work. If #208 does not get merged, we should still bring in these changes separately.

[adriangb]

One big question here is: is it time to bump the minimum Python version to 3.7? This would allow us:

• To use from __future__ import annotations
• To bump numpy up to v20, which includes typing support.
• To use the autodoc_type_aliases option in Sphinx to convert Union[bool, int, float, complex, _SupportsArray, Sequence] -> ArrayLike (see Support typing scikit-learn/scikit-learn#16705 (comment), Support typing scikit-learn/scikit-learn#16705 (comment)).

[stsievert]

I don't think #208 will get merged; you've got a better implementation in #210, and I don't want to deal with merge conflicts.

What's the current Python version?

What's the current Python version? It looks like the only user-facing advantage is around ArrayLike documentation. Is that accurate?

[adriangb]

The current Python version is 3.6.

Yes, as far as I can tell the only user advantage is documentation.

[stsievert]

Could that benefit be obtained if the docs were built with Python >= 3.7?

[adriangb]

I don't think so, because there needs to be __future__ import statements. Although maybe those can be put in try/except blocks?

[adriangb]

I think another alternative would be to move forward with implementing these type hints in 3.6. I think this would be really helpful for IDE auto-complete, etc.

For docs, we'll manually hardcode the "type" in the docstrings, which in practice just means changing array-like -> ArrayLike to match the actual type hints. I don't see how this is really a regression over what we currently have.