автомодуль sphinx: как ссылаться на классы в одном модуле? - PullRequest
Новая
       25

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

22 голосов
/ 13 октября 2011

Я пытаюсь использовать расширение sphinx autodoc и, в частности, директиву automodule для автоматического создания документации для приложения 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-ссылка к A-XXXX?Есть ли простой способ сделать это?Заранее спасибо за помощь.

Ответы [ 2 ]

43 голосов
/ 13 октября 2011

Вы можете сослаться на такой класс: 

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

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

9 голосов
/ 13 октября 2011

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