Sphinx / autodoc：如何交叉 link 到另一页上记录的函数

Question

我正在使用 Sphinx 构建我的 Python 包的文档。

我有一个 API.rst 文件，其中我列出了我的函数如下： .. autofunction:: mymodule.foo.bar1

对于此页面自动记录的不同功能，我可以举个例子：

:func:`foo1`

在 foo2() 的文档字符串中，它将为第一个函数创建一个 link。

但是，如果我有第二个文件 API2.rst，我在其中自动记录了一些其他函数，则似乎无法在不同页面中找到相同的语法 link。甚至 See Also 函数也不是 linked。

有没有办法跨页面指定和link不同的功能？谢谢

例子

可以找到 repo 的文档 here
例如，在 this function, under the parameter peaks, I am trying to link to another function called ecg_peaks() which is documented here

Answer 1

总结一下其他评论者的发现，当 Sphinx 解析 Python cross-references 时，它可以通过多种方式找到 cross-reference 目标。让我们举个例子。

假设您有以下项目结构

my-project/
├── docs/            # Where your docs, and conf.py are
└── my_project/      # where the Python code is, importable from Sphinx
    ├── __init__.py  # empty file
    ├── foobar.py    # defines the foo_func and bar_func functions
    └── baz.py       # defines the Baz class which as a baz_meth method

绝对限定名：文档中的任何地方应该可以做一个完全合格的参考，像这样
```
See the :func:`my_project.foobar.foo_func` function
```
相对名称：在给定的模块中，可以使用Python 直接对象名称。例如，从内部来自 foobar.py 文件：
```
See the :func:`foo_func` function.
```
宽松的限定名：引用python对象时您可以使用 . 字符来扩展对您的目标的搜索 space。例如，来自 foobar.py 文件：
```
See the :func:`.foo_func` function.
```
此外，来自 Baz 的 class 文档字符串，在 baz.py:
```
See the :meth:`.baz_meth` method.
```
宽松方法的风险是 Sphinx 会 link 它找到的第一件事，可能不是目标如你所愿。

最后，为了帮助防止这些问题，请转到 public，使用 nitpick option

以下是 Sphinx documentation 对这个话题的看法

The name enclosed in this markup can include a module name and/or a class name. For example, :py:func:filter could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :py:func:foo.filter clearly refers to the filter function in the foo module.

Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python’s codecs module, :py:func:open always refers to the built-in function, while :py:func:.open refers to codecs.open().

A similar heuristic is used to determine whether the name is an attribute of the currently documented class.

Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:.TarFile.close references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

Note that you can combine the ~ and . prefixes: :py:meth:~.TarFile.close will reference the tarfile.TarFile.close() method, but the visible link caption will only be close().

Sphinx / autodoc：如何交叉 link 到另一页上记录的函数

Sphinx / autodoc: how to cross-link to a function documented on another page

python

python-sphinx

restructuredtext

read-the-docs

autodoc

例子