python - example - sphinx automodule: ¿cómo hacer referencia a las clases en el mismo módulo?

sphinx documentation example

Question

Estoy tratando de usar la extensión autodoc sphinx y específicamente la directiva automodule para generar automáticamente la documentación para la aplicación django en la que estoy trabajando. El problema es que quiero crear referencias internas a diferentes clases dentro del módulo, sin tener que usar autoclase y autofuncionamiento en cada clase / función dentro del proyecto. Para un archivo fuente como este:

# 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

Me gustaría poder tener un archivo de documentación de esfinge como este:

.. automodule: source_code

¿Qué referencia puedo usar para XXXX-some-reference-to-A-XXXX? ¿Hay una manera fácil de lograr esto? Gracias de antemano por tu ayuda.

Answer 1

No sé si entiendo el problema, pero esto me funciona perfectamente con autodoc, según los objetos de Python de referencias cruzadas

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

Answer 2

Puede hacer referencia a una clase como esta:

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

Sphinx intentará inteligentemente averiguar a qué estás haciendo referencia. Si hay varias clases con el nombre A , puede recibir una advertencia, pero debería seleccionar la que se encuentra en el módulo actual.