python - 如何在 Sphinx 中为 Python 类/属性/常量/方法指定别名？

Question

我目前正在使用 Sphinx 编写 Python 模块的文档。

在记录一些函数时，如果发现自己写了类似这样的东西:

"""
Some documentation.

:param foo: My param.
:raises my_module.some.wicked.but.necessary.hierarchy.MyException: Something bad happenned.
"""

这工作正常，Sphinx 甚至将 my_module.some.wicked.but.necessary.hierarchy.MyException 链接到我的异常类的文档。

但是，我在这里看到两个问题:

• 必须键入异常的完整模块路径是乏味的。没什么大不了的，但我可以理解这如何在实际解析文档时避免歧义。所以我可能会接受这一点。
• 生成的文档还列出了完整的名称(包括模块路径)。

第二点使输出变得相当难以阅读而且一点也不好看。它使文档变得杂乱无章，而且没有带来太多好处，因为无论如何都可以单击链接来获取异常类的完整定义。

我尝试将其写为相对路径(例如使用 ..hierarchy.MyException，但 Sphinx 找不到该类并且链接会断开)。

每当我引用我的异常类时，有没有办法定义一个默认的别名/标题来代替完整路径？我显然希望链接保持原样:我只想要一个更好(更短)的标题。

如果不是，在 Sphinx 的某处是否有一个选项告诉它避免显示某些对象的完整模块路径？某种选择？

Answer 1

尝试:

:raises :py:class:`~.MyException`: something bad happened