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 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?
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: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 theobjtype
as'instanceattribute'
and this line insphinx.ext.napoleon.docstring
where inline comments are only parsed for'attribute'
,'data'
, or'property'
. I see that the commented outimport_object
method used to "disguise" the instance attribute as'attribute'
, and simply changing the class levelobjtype
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 documentdynamicprops
added in the constructor.Thanks for the really useful package!