31

我正在尝试使用 sphinx autodoc扩展，特别是automodule为我正在开发的 django 应用程序自动生成文档的指令。问题是我想在模块中创建对不同类的内部引用，而不必在项目中的每个类/函数上使用autoclass和。autofunction对于这样的源文件：

# source_code.py
class A:
    """docs for A
    """
    pass

class B:
    """docs for B with 
    :ref:`internal reference to A <XXXX-some-reference-to-A-XXXX>`
    """
    pass

我希望能够拥有这样的 sphinx 文档文件：

.. automodule: source_code

我可以为 XXXX-some-reference-to-A-XXXX 使用什么参考？有没有简单的方法来实现这一点？在此先感谢您的帮助。

4

2 回答 2

55

您可以像这样引用一个类：

class B(object):
    """docs for B with reference to :class:`.A`"""
    pass

Sphinx 将智能地尝试找出您所引用的内容。如果有多个具有 name 的类A，您可能会收到警告，但它应该选择当前模块中的一个。

于 2011-10-13T12:33:55.770 回答
14

不知道我是否理解这个问题，但根据交叉引用 Python 对象，这对我来说使用 autodoc 完美无缺

class FlowDirection(GeneralTable):
    '''
    Heat Flow Direction

    :cvar int id: database primary key
    :cvar unicode name: name 
    '''
    def __repr__(self):
        return u'<FlowDirection {0} instance at {1}>'.format(
                self.name, hex(id(self))).encode('utf-8')

    def __unicode__(self):
        return self.name

class AirCavityRes(GeneralTable):
    '''
    Air Cavity :term:`thermal resistance`

    :cvar flow_direction: heat flow direction
        (see :class:`FlowDirection`)
    :cvar int id: database primary key
    :cvar int if_fd: database foreign key to :class:`FlowDirection`
    :cvar float res: :term:`thermal resistance`
    :cvar float thick: thickness
    '''
    def __repr__(self):
        return u'<AirCavityRes {0} instance at {1}>'.format(
                self.res, hex(id(self)))
于 2011-10-13T12:31:21.063 回答