Sphinx for Python 中函数或类的交叉参考文档

问题描述

我想要在解释性文档中引用 Python 类的文档，稍后再引用它的构造函数。所以想象有一个文件

svg {
  background: green;
  max-height: 75vh;
  width: 100%;
  max-width: calc(75vh * 23 / 29);
}

和我的第一个文件

# MyLib/MyClass.py
class MyClass:
    """Class Introduction"""
    def __init__(paramX):
        """:param paramX: Xes out things"""

如何使参考工作：我需要在 Sphinx 文件中如何以及在何处包含 Python 文件，以及如何定义（在 Python 文件中）和解析（在 rst 文件中）参考？预期的输出将是这样的：

#MyLib/docs/source/MyDoc.rst
Some text where :ref:`here` is my reference to "Class Introduction"
 and :ref:`there` follows my reference to the __init__ method documentation

其中括号 <..> 包含指向文档的链接，文档本身出现在“和”之后，在第一个文件中分别由 Some text where <link to documentation of class _MyClass_>... and 'class MyClass def __init__(paramX): paramX: Xes out things' 和 :ref:`here` 引用。

解决方法

来自问题中的示例模块 ref_constructor.py

class MyClass:
    """Class Introduction."""
    def __init__(paramX):
        """The docstring of constructor.

        :param paramX: Xes out things.
        :type paramX: str
        """

使用 reST 文件 ref_constructor.rst 请注意选择适当的角色，在本例中为 :class: 和 :meth:

Reference to class constructor
------------------------------

.. automodule:: ref_constructor


.. here begins de documentation.

Some text where :class:`ref_constructor.MyClass` is my reference to "Class Introduction"
and :meth:`ref_constructor.MyClass.__init__` follows my reference to the __init__ method documentation.


Some text where :class:`MyClass` is my reference to "Class Introduction"
and :meth:`MyClass.__init__` follows my reference to the __init__ method documentation.

您可以根据上下文使用完全限定名称或缩写形式编写交叉引用

Cross-referencing Python objects

包含在此标记中的名称可以包括模块名称和/或类名称。例如，:py:func:`filter` 可以引用当前模块中名为 filter 的函数，或该名称的内置函数。相比之下，:py:func:`foo.filter` 显然是指 foo 模块中的过滤器函数。

结果