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

Question

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

# 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'

如所述，括号 <..> 在文档中包含一个 link，文档本身出现在 'and' 之后，在第一个文件中由 :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.

结果

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

Cross reference documentation of function or class in Sphinx for Python

python

python-sphinx

autodoc

cross-reference