Properties vs. attributes keywords

[ryancoe]

MATLAB uses the keyword Properties, but sphinx would prefer Attributes. Is there a way to get around this (i.e., and still have help(classname) work in MATLAB)?

https://www.mathworks.com/help/matlab/matlab_prog/create-help-for-classes.html

MATLAB would like:

% <classname> Properties:
%  prop1 - definition
% ...

Sphinx would like:

% Attributes::
% ...

@H0R5E

[joeced]

Hi

Yes it's kind of conflicting. I'll try to see if there is any was around this.

[denisrosset]

@ryancoe I was pretty frustrated by the state of the Mathworks tooling that I ended up writing a code preprocessor that does that kind of shuffling, plus a replacement for the help function (as help doesn't understand inheritance!).

Thus it's a pile of transformers (preprocessor, matlabdomain, finally Sphinx), but it finally gives us what we want!

See https://replab.github.io/replab/

[H0R5E]

My current workaround for this is to double up on the documentation for MATLAB classes and hide the MATLAB syntax docs from Sphinx by using the autodoc-process-docstring event to exclude docs between "--" markers. For example, the docstrings of one of our classes is show below, which gives the proper linking behaviour when called with help and doc and compiles OK with Sphinx. The main downside is that the MATLAB docs also shows the Sphinx formatted part.

classdef Device < WecOptTool.base.AutoFolder
    % Class representing a device with a given geometry, model and 
    % contoller configuration. Device objects should only be created using 
    % the ``makeDevice`` method of :mat:class:`+WecOptTool.Blueprint` 
    % objects.
    %
    % Attributes:
    %     folder (string): path to data storage folder
    %     geomType (string):
    %         The geometry type associated to this device.
    %     geomParams (cell array):
    %         The geometry definition parameters for this device.
    %     controlType (string):
    %         The controller type associated to this device.
    %     controlParams (cell array):
    %         The controller definition parameters for this device.
    %     modelParams (optional cell array):
    %         The model definition parameters for this device. Defaults to
    %         empty cell array.
    %     hydro (:mat:class:`+WecOptTool.+types.Hydro`):
    %         The Hydro object assosiated to this device geometry
    %     seaState (:mat:class:`+WecOptTool.+types.SeaState`):
    %         The SeaState object passed to the last call of `simulate`.
    %         Empty by default.
    %     motions (array of :mat:class:`+WecOptTool.+types.Motion`):
    %         The Motion objects generated by the last call of `simulate`,
    %         per sea state. Empty by default.
    %     performances (array of :mat:class:`+WecOptTool.+types.Performance`)
    %         The Performance objects generated by the last call of 
    %         `simulate`, per sea state. Empty by default.
    %     aggregation (optional)
    %         If the Blueprint.aggregationHook property is defined, the
    %         result of that function is added here.
    %
    % --
    %
    % Device Properties:
    %     folder - path to data storage folder
    %     geomType - The geometry type associated to this device.
    %     geomParams - The geometry definition parameters for this device.
    %     controlType - The controller type associated to this device.
    %     controlParams - The controller definition parameters for this 
    %                     device.
    %     modelParams - The model definition parameters for this device. 
    %                   Defaults to empty cell array.
    %     hydro - The Hydro object assosiated to this device geometry
    %     seaState - The SeaState object passed to the last call of 
    %                simulate. Empty by default.
    %     motions - The Motion objects generated by the last call of 
    %               simulate, per sea state. Empty by default.
    %     performances - The Performance objects generated by the last 
    %                    call of simulate, per sea state. Empty by default.
    %     aggregation - If the Blueprint.aggregationHook property is 
    %                   defined, the result of that function is added here.
    %
    % Device Methods:
    %     simulate - Determine the performace of the WEC device
    %     saveFolder - Save the data folder and contents
    %
    % See also WecOptTool.Device, WecOptTool.types
    %
    % --

[joeced]

Is the work-around acceptable. Can I close the issue?

[denisrosset]

For me it's already been worked around. @H0R5E we ended up rewriting our own help wrapper; I wouldn't encourage anybody to go down that route however

[rdzman]

Just getting started with Sphinx and Matlab and running into the same issue.

My 2 cents ... any workaround that requires you to manual document each attribute/property twice (once for MATLAB, once for Sphinx) is far from acceptable. It practically defeats the purpose of using Sphinx.

[joeced]

I think I'll prioritize this issue. I haven't used this feature in MATLAB myself, as I typically "just" document properties by themselves, so not mentioning them in the class definition docstring. However, I can clearly see the benefit, as it would limit where you need to write documentation. The work for me would lie in parsing the class definition property docstrings.

[rdzman]

It sounds like maybe I'm missing something ... I'm having trouble even using the property and method docstrings effectively, but I'll take those questions to a new issue — #140.

[joeced]

Fixed in version 0.19.1