Sphinx automodule: как ссылаться на классы в одном модуле?

Я пытаюсь использовать расширение sphinx autodoc и, в частности, директиву автомодуля для автоматической генерации документации для приложения django, над которой я работаю. Проблема в том, что я хочу создавать внутренние ссылки на разные классы внутри модуля, без необходимости использования автокласса и автофункции для каждого отдельного класса/функции внутри проекта. Для исходного файла следующим образом:

# 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? Есть ли простой способ сделать это? Заранее благодарим за помощь.

Ответы

Ответ 1

Вы можете ссылаться на класс следующим образом:

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

Сфинкс разумно попытается выяснить, что вы ссылаетесь. Если есть несколько классов с именем A, вы можете получить предупреждение, но оно должно забрать его в текущем модуле.

Ответ 2

Не знаю, понимаю ли я проблему, но это работает безупречно для меня с autodoc, согласно перекрестным ссылкам на объекты Python

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)))