Sphinx :ivar tag goes looking for cross-references

Question

I want to document Python object attributes with Sphinx. I understand I should use

:ivar varname: description
:ivar type varname: description

Answer 1

There's an alternative with other advantages. Just define you member variables at class scope and document them with plain docstring. Later you can reference them with py:attr: role. It's more readable, self-documented (yeah, I know this is under python-sphinx, but anyway) and introspection-friendly approach.

module.py

class A:

    x = None
    '''This way there's no issue. It is more readable and friendly
    for class member introspection.'''


    def __init__(self, x):
        self.x = x

class B:
    '''Something about :py:attr:`.A.x`'''

    def x(self):
        '''Method x of B'''
        return 1

README.txt

****
Test
****

.. autoclass:: module.A
   :members:

.. autoclass:: module.B
   :members:

conf.py

extensions = ['sphinx.ext.autodoc']

source_suffix = '.txt'

master_doc = 'README'

project = 'Test'

pygments_style = 'sphinx'

html_theme = 'alabaster'

html_use_index       = False
html_show_sourcelink = False
html_show_copyright  = False

html_sidebars = {'**': ['localtoc.html']}

Build like PYTHONPATH=. sphinx-build . html.