search

sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
Other
64 stars 45 forks source link

Napoleon reformulation does not get applied to `MatProperty` docstrings. #250

Closed apozharski closed 1 month ago

apozharski commented 1 month ago

Hello, I recently ran into what is either a bug (or perhaps unsupported behavior). When using sphinx.ext.napoleon style inline docstrings for properties, for example:

classdef IAmAClass
    properties
        i_am_a_property % IAmAType: this property has a type in the comment
    end 
end

napoleon ignores the Type: rest of docstring syntax and does not correctly reformulate is with :type: IAmAType

My understanding of sphinx internals is certainly not complete but from digging around in pdb it seems like it is a combination of this line in MatInstanceAttributeDocumentor which sets the objtype as 'instanceattribute' and this line in sphinx.ext.napoleon.docstring where inline comments are only parsed for 'attribute', 'data', or 'property'. I see that the commented out import_object method used to "disguise" the instance attribute as 'attribute', and simply changing the class level objtype does fix this bug.

Reading through the rest of the codebase this does not seem to ever be used for anything internally however you likely have better insight whether this is simply a hack or a valid approach. From a high level it seems to me that the distinction between 'attribute' and 'instanceattribute' are moot in matlab unless one also wants to document dynamicprops added in the constructor.

Thanks for the really useful package!

joeced commented 1 month ago

Thanks for the report. I think you are right, that we could simplify the number of documenters for MATLAB. Do you have some Sphinx example I can add as a test?