CODEWITHSUNDEEP
pythondjangopython-sphinxautodoc
dino
dino

Reputation: 3307

Sphinx automodule: how to reference classes in same module?

I am trying to use the sphinx autodoc extension and specifically the automodule directive to automatically generate documentation for django app I am working on. The problem is that I want to create internal references to different classes within the module, without having to use autoclass and autofunction on every single class/function within the project. For a source file like this:

# 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

I would like to be able to have a sphinx documentation file like this:

.. automodule: source_code

What reference can I use for XXXX-some-reference-to-A-XXXX? Is there an easy way to accomplish this? Thanks in advance for your help.

Upvotes: 35

Views: 32549

Answers (2)

neurino
neurino

Reputation: 12445

Don't know if I understand the problem but this works flawlessly to me with autodoc, as per Cross-referencing Python objects

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

Upvotes: 15

jterrace
jterrace

Reputation: 67163

You can reference a class like this:

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

Sphinx will intelligently try and figure out what you're referencing. If there are multiple classes with the name A, you might get a warning, but it should pick up the one in the current module.

Upvotes: 61

Related Questions