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

Question

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

我正在使用 sphinx 来记录它，并且在我的 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 的文档类(class)。但缺少的是执行此操作的能力:

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 解决。如果在本地对象 list 中找不到名称，它可以在外部资源中搜索。您可以将自己的文档添加为 intersphinx list 。

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?