:attr: and :meth: links require class name

[rdzman]

Given a class MyClass with a method my_method(), it does not seem possible to create a link to the method with just the method name (e.g. using :meth:`my_method`). Rather it requires including the class name as well to get the link (e.g. :meth:`MyClass.my_method`), but then the class name is also displayed as the link text. Likewise for properties when using :attr:.

This does not appear to be the case with Python autodoc, based on on-line examples of what I assume is documentation generated using Sphinx autodoc. An example would be the data_version link in the 3rd paragraph of the Sphinx Domain API. The source says :attr:`data_version`, but the link points to sphinx.domains.Domain.data_version as one would expect.

It would be nice if it worked this way for matlabdomain as well.

Not sure if this is a bug report or a feature request ... but hopefully it's not too hard to fix.

[joeced]

I wasn't aware of this feature of the Python domain! That would make things so much easier for making auto-links in docstrings akin to how MATLAB does it.

Given

classdef myClass
    % myClass   Summary of myClass
    % This is the first line of the description of myClass.
    % Descriptions can include multiple lines of text.
    %
    % myClass Properties:
    %    a - Description of a
    %    b - Description of b
    %
    % myClass Methods:
    %    doThis - Description of doThis
    %    doThat - Description of doThat

    properties
        a
        b
    end

    methods
        function obj = myClass
        end
        function doThis(obj)
        end
        function doThat(obj)
        end
    end

end

We could then just replace the property and method names with

classdef myClass
    % myClass   Summary of myClass
    % This is the first line of the description of myClass.
    % Descriptions can include multiple lines of text.
    %
    % myClass Properties:
    %    :attr:`a` - Description of a
    %    :attr:`b` - Description of b
    %
    % myClass Methods:
    %    :meth:`doThis` - Description of doThis
    %    :meth:`doThat` - Description of doThat

...

end

[rdzman]

Exactly!

[joeced]

Definitely on the things to work on next.

[rdzman]

Ran into this one again.

With auto-linking turned on I have a workaround for methods, as mymethod() gets automatically converted into :meth:`mymethod() <myclass.mymethod>`.

But for properties, I still don't have a workaround. I could use code similar to the auto-linking code to modify the docstring directly to replace :attr:`myproperty` with :attr:`myproperty <myclass.myproperty>`, but that feels like a hack.

@joeced, have you made any progress on this? Or do you have any thoughts?

[joeced]

No progress yet. I'll try to work on it in the coming week.

[rdzman]

Just wanted to add a quick note here while I'm thinking about it, since I ran into this issue again.

It should be possible to link to the proper method or attribute from any docstring in the class. That is, from a method docstring or property/attribute docstring, not just the class docstring itself. This should be included in the tests for this functionality when implemented.