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

Question

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

当我记录一些函数时，如果我发现自己写的东西如下：

"""
Some documentation.

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

这很好，狮身人面像甚至将my_module.some.wicked.but.necessary.hierarchy.MyException链接到我的异常类的文档中。

然而，我在这里可以看到两个问题：

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

这第二点使输出很难读懂，而且一点也不好看。它把文档弄得乱七八糟，而且不会带来太多，因为我们可以点击链接来获得异常类的完整定义。

我试着把它写成一个相对路径(例如使用..hierarchy.MyException，但是Sphinx找不到类，链接就会中断)。

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

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

Answer 1

试着：

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