Intersphinx mapping not working in Returns

GenericMappingTools / pygmt

A Python interface for the Generic Mapping Tools.

https://www.pygmt.org

BSD 3-Clause "New" or "Revised" License

759 stars 220 forks source link

Intersphinx mapping not working in Returns #937

Closed maxrjones closed 3 years ago

maxrjones commented 3 years ago

Description of the problem

The intersphinx mapping to pandas.DataFrame does not seem to be working in the Returns section of the docstrings. See blockmedian for an example.

Originally posted by @weiji14 in https://github.com/GenericMappingTools/pygmt/pull/930#discussion_r579526151

maxrjones commented 3 years ago

Relevant issue: https://github.com/sphinx-doc/sphinx/issues/8290

Seems the options here are to either set napoleon_use_rtype = True in doc/conf.py, manually define the links, or wait for a bug fix.

seisman commented 3 years ago

Tried napoleon_use_rtype = True, it gives:

seisman commented 3 years ago

napoleon_use_rtype = True gives inconsistent rendering for returns and parameters. I don't think this is what we want. I think we should manually define the links or just ignore them.

maxrjones commented 3 years ago

My preference would be to ignore the missing links in the rtypes (seems like an upstream bug to me) and manually define the links in the bullet lists (if present) below the rtypes (which would not be automatically linked regardless of the bug). These are the module docstrings which would need to be updated if we chose this solution:

[x] blockmedian.py (L61)
[x] grdcut.py (L85)
[x] grdfilter.py (L119)
[x] grdtrack.py (L66)
[x] info.py (L66)

seisman commented 3 years ago

My preference would be to ignore the missing links in the rtypes (seems like an upstream bug to me) and manually define the links in the bullet lists (if present) below the rtypes (which would not be automatically linked regardless of the bug).

Sounds good.