Annotations should perhaps not be rendered in the docs using `:py:class:`

anntzer commented 7 years ago

Consider the apidocs, using sphinx-autodoc-typehints, of

def f1(x):
    """
    A function.

    :param int x: The x.
    """

def f2(x: int):
    """
    A function.

    :param x: The x.
    """

By default, for f1, int is rendered in italic while for f2, it is rendered in bold. This is due to the fact that sphinx-autodoc-typehint adds a :py:class: in front of the typename.

While this may be semantically correct, this is inconsistent with sphinx's default recommendation (http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists), so I think this should be off by default.

auscompgeek commented 6 years ago

I think it'd make sense to not add the :class: for builtins, since they're not going to link anyway for pretty much every project using Sphinx.

auscompgeek commented 5 years ago

Revisiting this, it looks like Sphinx tries to link unannotated types automatically, but it won't look in any intersphinx docs.

It also turns out the Python docs actually has an intersphinx database as well, so I guess this behaviour should be configurable.

gaborbernat commented 2 years ago

Please check again with latest release and report back if the problem is still active.

tox-dev / sphinx-autodoc-typehints

Annotations should perhaps not be rendered in the docs using `:py:class:` #21