formatting of property defaults

[rdzman]

If matlab_show_property_default_value is set to True, a numerical default value is displayed in single quotes (e.g. prop = '10' and a char array default value is displayed in double quotes (e.g. prop = "my_string_default"). I haven't tried other types of values yet, but it seems to me that it makes more sense to display the default value directly as specified in the code.

Replacing these lines ...

https://github.com/sphinx-contrib/matlabdomain/blob/f9dcfef952294b48087bfb735f13c4bec260f934/sphinxcontrib/mat_documenters.py#L1035-L1037

... with ...

    objrepr = self.object.default

... results in what I'm looking for, at least for these two simple examples. That is, I get prop = 10 and prop = 'my_string_default', respectively. However, I don't know what sphinx.util.inspect.object_description() does, so I'm not sure if this is a safe fix.

Oh, and to get it to work, this line ... https://github.com/sphinx-contrib/matlabdomain/blob/f9dcfef952294b48087bfb735f13c4bec260f934/sphinxcontrib/mat_documenters.py#L1042

... also needs to be changed to ...

    objrepr == None

Thoughts?

[joeced]

I briefly looked at this when implementing the matlab_show_property_default_value feature. It could definitely be simplified a lot. It looks like a left-over from the Python autodoc. We just want the string to displayed.

I started on this here: https://github.com/sphinx-contrib/matlabdomain/tree/property-default-value-rendering

I also tested the test_docs and setting the matlab_show_property_default_value = True in the conf.py file.

Given this input:

Renders like this:

The strings are just printed verbatim, and the last one stripped the .... Any thoughts on how diligently we should try to clean up the property default value?

[rdzman]

I tend to have very simple default property values, if any, so personally I don't have strong opinions on this.

Here's an idea, though ... if it's too complicated to make sure that all of these edge cases display correctly, what about simply displaying the first line of the default verbatim, including any ellipsis that might be there, and skip the subsequent lines. That way it should be correct, though potentially incomplete. I think I'd prefer to guarantee that what is displayed is correct (but possibly incomplete) rather than risk displaying something that is more complete but potentially incorrect.

Oh, and I do think we should keep the = sign between the name of the property and the default value, which seems to be missing in your screenshot above.

[joeced]

Excellent idea! I changed multiline default values (which are probably pretty rare in the wild) to just print the first and last part, joined with an ellipsis. Thus we achieve, single-line property default values.

[joeced]

A PR is ready https://github.com/sphinx-contrib/matlabdomain/pull/176. Feel free to comment :)

[joeced]

Fixed in #176