python - Sphinx for Python 中函数或类的交叉引用文档

Question

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

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

和我的第一个文件

#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

我怎样才能让引用起作用:我需要如何以及在 Sphinx 文件中的什么位置包含 Python 文件，以及如何定义(在 Python 文件中)和解析(在第一个文件中)引用？预期的输出将是这样的:

Some text where <link to documentation of class _MyClass_>...
 and 
    'class MyClass
        def __init__(paramX):
           paramX: Xes out things'

如所述，方括号 <..> 包含指向文档的链接，文档本身出现在“和”之后，在第一个文件中由 :ref:`here` 和 :ref:`there` ，分别。

Answer 1

从问题中的示例模块 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

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.

结果