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

Я пытаюсь использовать расширение 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

Я хотел бы иметь такой файл документации по сфинксу:

.. automodule: source_code

Какую ссылку я могу использовать для XXXX-some-reference-to-A-XXXX? Есть ли простой способ добиться этого? Заранее спасибо за помощь.


python django python-sphinx autodoc
person dino    schedule 13.10.2011    source источник

Ответы (2)


arrow_upward
55
arrow_downward

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

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

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

person jterrace    schedule 13.10.2011

arrow_upward
15
arrow_downward

Не знаю, понимаю ли я проблему, но для меня это работает безупречно с 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)))
person neurino    schedule 13.10.2011