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.