Intersphinx mapping not working in Returns

[maxrjones]

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 #930 (comment)

[maxrjones]

Relevant issue: sphinx-doc/sphinx#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]

Tried napoleon_use_rtype = True, it gives:

[seisman]

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]

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:

• blockmedian.py (L61)
• grdcut.py (L85)
• grdfilter.py (L119)
• grdtrack.py (L66)
• info.py (L66)

[seisman]

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.