search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.6k stars 2.13k forks source link

autodoc type hints and intersphinx aren't working with the `requests` public API #9653

Closed bhrutledge closed 3 years ago

bhrutledge commented 3 years ago

Describe the bug

It looks like autodoc is resolving type hints like requests.Response to their internal definition, e.g. requests.models.Response. This means the intersphinx references to the Requests API docs don’t work, resulting in build messages like WARNING: py:class reference target not found: requests.models.Response.

Based on my limited understanding, I think this might actually be an issue with Requests, but I thought I'd start here.

How to Reproduce

I put an example repo with instructions up at https://github.com/bhrutledge/sphinx-requests-typehints, generated via sphinx-apidoc. The rendered docs are at https://sphinx-requests-typehints.readthedocs.io/en/latest/example_package.html.

Expected behavior

It'd be nice if the types for requests classes in argument defaults and parameters were linked to the Requests documentation.

Your project

https://github.com/bhrutledge/sphinx-requests-typehints

Screenshots

No response

OS

Mac

Python version

3.9.7

Sphinx version

4.2.0

Sphinx extensions

sphinx.ext.autodoc, sphinx.ext.intersphinx

Extra tools

requests

Additional context

No response

kotfu commented 3 years ago

I have the same problem. I observe that if you have a docstring on the class which contains:

Uses :class:`requests.Response` to fetch the url

sphinx successfully locates and links the proper page in the requests documentation.

There must be some difference between resolving and locating the type hint and resolving and locating the cross-reference.

kotfu commented 3 years ago

I also note that when using Sphinx 4.1 the provided example project does not generate a warning, although it renders the requests.Response type hint as requests.models.Response.

I'm not very familiar with the Sphinx source code, but reviewing the changelog for 4.2 I wonder if #9576 changed this behavior.

kotfu commented 3 years ago

Providing a type hint of requests.models.Response doesn't fix the issue either, you get the same error.

tk0miya commented 3 years ago

It seems the document of requests was built by Sphinx-1.8.5. So an index entry for requests.models.Reponse is not generated. This problem will be resolved by upgrading Sphinx to 4.0 or newer. https://readthedocs.org/projects/requests/builds/14778070/

Can anyone report this to the requests project?

bhrutledge commented 3 years ago

Can anyone report this to the requests project?

Done: https://github.com/psf/requests/issues/5954

bhrutledge commented 3 years ago

Resolved in https://github.com/psf/requests/pull/5956.