sphinx超链接到以别名导入的Python模块的成员

Question

我维护一个Python软件包，通常以import numpy as np或import pandas as pd的方式导入一个简短的标准化昵称。假设它是import foobar as fb。

我正在使用狮身人面像对其进行记录，并且在我的conf.py中，我的'sphinx.ext.autodoc'和extensions中有default_role = 'py:obj'。这是一个不错的设置，因为它意味着每当我的文档字符串或单独的.rst文件包含整齐的字符串，例如

See the `foobar.Thing` class documentation for more details. 

甚至只是

See the `Thing` class documentation for more details.

然后，反引号内的文本将自动超链接到foobar.Thing类的文档。但是缺少的是这样做的能力：

See the `fb.Thing` class documentation for more details.

文本fb.Thing不会超链接，因为sphinx（或sphinx autodoc）不知道fb是foobar程序包的别名。我怎么知道是这种情况？

注意：我知道可以用<>表示法来做：

See the `fb.Thing <foobar.Thing>` class documentation for more details.

但是文档字符串也被设计为以纯文本格式读取，因此我希望可以在不将这种或其他形式的:clutter:`...`引入其中的情况下完成此操作，而是希望以某种方式在conf.py文件或.. automodule::语句。

Answer 1

这可能可以用狮身人面像解决。如果在本地对象清单中找不到名称，则可以在外部资源中搜索。您可以添加自己的文档作为狮身人面像库存。

Intersphinx配置：

# ==============================================================================
# Sphinx.Ext.InterSphinx
# ==============================================================================
intersphinx_mapping = {
#  'python':       ('https://docs.python.org/3', None),
  'foobar': ('http://foobar.readthedocs.io/en/latest', None),
}

用法：

At next, I want to document `fb.Thing <foobar:Thing>`, because it's a great implementation.

其他资源：

• Intersphinx文档：https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
• 有时，Sphinx可以处理别名：Overriding Sphinx autodoc "Alias of" for import of private class?

Answer 2

我不知道如何使狮身人面像知道模块别名，但这可能接近您想要的符号：

somefile.py：

"""
Some documentation with references to an externally documented function

:func:`numpy.searchsorted` or :func:`partial.update_wrapper`
"""

conf.py：

# intersphinx settings
intersphinx_mapping = {'numpy': ('https://docs.scipy.org/doc/numpy', None),
                       'functools': ('https://docs.python.org/3.7/library/functools.html', None)}