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

发布于 2025-01-20 09:04:46 字数 867 浏览 2 评论 0 原文

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

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

对于自动记录于此的不同函数例如，我可以

:func:`foo1`

在 foo2() 的文档字符串中放置：，它将创建指向第一个函数的链接。

但是，如果我有第二个文件 API2.rst，其中我自动文档化了一些其他函数，则相同的语法似乎无法找到不同页面之间的链接。甚至连See Also 功能也没有链接。

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

示例

该存储库的文档可以在此处找到
，例如，在此文档字符串函数，在参数peaks下，我试图链接到另一个名为ecg_peaks()的函数，该函数已记录此处

原文

I am building a documentation of my Python package using Sphinx.

I have a API.rst file, in which I list my functions as follows: .. autofunction:: mymodule.foo.bar1

For the different functions that are autodocumented form this page, I can put for instance:

:func:`foo1`

in the docstring of foo2() and it will create a link to the first function.

However, if I have a second file API2.rst, in which I autodoc some other functions, the same syntax doesn't seem to find the links across different pages. Even the See Also functions are not linked.

Is there a way to specify and to link different functions across pages? Thanks

Example

The repo's documentation can be found here
For instance, in the docstring of this function, under the parameter peaks, I am trying to link to another function called ecg_peaks() which is documented here

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

ゞ记忆︶ㄣ 2025-01-27 09:04:46

为了总结其他评论者发现的内容，当Sphinx解决Python交叉引用时，它可以通过多种方式找到交叉引用目标。让我们举一个例子。

假设您有以下项目结构

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

绝对合格名称：您的文档中的任何地方
应该能够做出完全合格的参考
```
 请参阅：func：`my_project.foobar.foo_func`函数
 
```
相对名称：在给定的模块中，您可以使用Python
直接对象名称。例如，从
来自foobar.py文件：
```
 请参见：func：`foo_func`函数。
 
```
放松的合格名称：引用python对象时
您可以使用。字符来扩展目标的搜索空间。例如，来自foobar.py文件：
```
 请参阅：func：`.foo_func`函数。
 
```
另外，从Baz的类docString，in Baz.py：
```
 参见：meth：`.baz_meth`方法。
 
```
放松方法的风险是狮身人面像会链接
第一件事发现，这可能不是目标
您期望。

最后，为防止这些问题公开，请使用

这是狮身人面像文档在此主题上说

此标记中包含的名称可以包括一个模块名称和/或
班级名称。例如，：py：func：过滤器可以参考函数
在当前模块中命名过滤器或该模块的内置功能
姓名。相反，：py：func： foo.foo.folter 显然是指该过滤器
在Foo模块中的功能。

通常，首先搜索这些角色中的名称，而无需再搜索
资格，然后使用当前的模块名称进行了准备，然后
当前的模块和班级名称（如果有）如果您的前缀
带有点的名称，此订单被颠倒了。例如，在
Python的编解码器模块的文档，：PY：func： Open 始终引用
对于内置功能，while：py：func： .open 是指
codecs.open（）。

使用类似的启发式方法来确定名称是否为
当前记录的类的属性

另外，如果该名称带有点，没有找到确切的匹配，则
目标被视为后缀和所有对象名称的后缀
被搜索。例如，：py：meth： .tarfile.close 参考
tarfile.tarfile.close（）函数，即使当前模块不是
tarfile。由于这可能会变得模棱两可，如果有多个
可能的匹配，您将从狮身人面像。

请注意，您可以组合〜和。前缀：
：py：meth：〜.tarfile.close 将引用tarfile.tarfile.close（）
方法，但是可见的链接字幕只会关闭（）。

To sum up what other commenters found, when Sphinx resolve Python cross-references, it can find the cross-reference targets in several ways. Let's get an example.

Say you have the following project structure

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

Absolute qualified name: Anywhere in your documentation you
should be able to make a fully qualified reference, like so
```
See the :func:`my_project.foobar.foo_func` function
```
Relative name: In a given module, you can use the Python
object name directly. For instance, from within the
from foobar.py file:
```
See the :func:`foo_func` function.
```
Relaxed qualified name: When referencing a python object
you can use the . character to extend the search space for your target. As an example, from foobar.py file:
```
See the :func:`.foo_func` function.
```
Also, from the class docstring of Baz, in baz.py:
```
See the :meth:`.baz_meth` method.
```
The risk with the relaxed method is that Sphinx will link
to the first thing it finds, which may of may not be the target
you expected.

Finally, to help prevent these issues go public, use the nitpick option

Here is what Sphinx documentation says on this topic

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().