single classdef documentation for MATLAB doc and Sphinx

[rdzman]

My goal is to have reference documentation for my classdef files that work fine with MATLAB's doc command and that I can use with this package and autodoc (and probably napoleon or something else) to generate basic HTML documentation for each class.

At the very least I need to be able to describe the class and each property and method, with the method signature and descriptions of each input and output argument. Ideally, classes could also be auto-linked to superclasses.

Could anyone who has successfully done this provide an example classdef file and corresponding conf.py and .rst file showing how you accomplish this?

1. At the moment I'm having multiple issues. I'm using something like the following in a .rst file ...

.. autoclass:: myBaseClass
    :members:

.. autoclass:: mySubClass
    :members:

... and it just creates a single list of properties and methods together. How do I get it to list them separately?

2. The property names are shown with = None after them, which I don't want.
3. Any properties or methods listed in the classdef docstring are combined into single paragraph.

Any help or pointers are greatly appreciated.

[joeced]

I think I adapted my documenting style, to what this package has been offering. It's based on the Sphinx auto-document feature for Python. This implied for me not listing methods and properties in classdef docstring. I can clearly see the advantage if users call help MyClass or doc MyClass in MATLAB, that you get everything listed with clickable link.This would require quite some work, where parsing/processing the classdef docstring, to something Sphinx can understand.

Regarding properties, yes currently we list all properties with = None, if no default value was given and the default value if there is one. This is inherited from Python auto-doc features. I could make an option to not show that.

A better summary would be definitely improve the usability of the package. I think we should strive for something that looks like the MATLAB version.

My problem is that I have very little free time to add features to this package, other than fixing errors. I will happily accept pull requests :)

Lastly, if you add a minimal example in zip-file I can take a look at it.

[rdzman]

Thanks @joeced, I understand the "little free time" constraint, so I appreciate your work on this project and any attention you can spare.

I've attached a minimal example (classdef-min-ex.zip) of my current best attempt at getting something that works with help, doc and Sphinx autodoc. I've included my HTML output in build/html. For comparison, I've also included the output of MATLAB's help command in build/matlab/help.png and MATLAB's doc command (via the undocumented help2html) in the HTML files in build/matlab.

Here are a list of some remaining issues (I'm sure there are more), in rough priority order:

1. I have not found a way to have it generate separate lists of properties and methods (:members:) under their own headings, i.e. Properties and Methods respectively. The are dumped out in a single list with no heading. I really need them listed separately in two clearly labeled lists.
2. I'd like to have method, property and class names in the descriptions be automatically highlighted and/or turned into links. At the very least in the See also line it should automatically link. Attempts to manually link or highlight for Sphinx break MATLAB's auto highlighting/linking. As it is you have to do it both ways if you want working links in both Matlab help and Sphinx documentation. And that's ugly.
3. As with the previous item, in the documentation for properties and methods in the class docstring (required for users of help to find properties/methods), anything I do to highlight the property or method name (e.g. double-back quotes) breaks the auto-created link under MATLAB help.
4. I'd prefer to eliminate the = None following the property names.
5. The :inherited-members: does not work in Matlab ☹️ . I suspect this is a hard one.

Thanks again for any suggestions (or tweaks to sphinx-contrib/matlabdomain 😃 ).

[joeced]

Sorry for the late reply. I have been on vacation.

Thanks for the example. It's much easier to understand what you would like. I will try to look into to this, as it could make it way easier to transition to Sphinx.

Unfortunately, I still have some dark spots around how Sphinx exactly works, and when we can modify certain elements.

[rdzman]

Currently, my highest priority blocker is item 1 in my previous comment, i.e. getting :members: to output separate lists of properties and methods with headings.

I'm totally unfamiliar with the code at this point, but could you point me where to look in the code to see whether I might be able to figure something out?

[joeced]

Having had some time to think about this feature request, I like it more and more.

The extension is built upon the Python auto-doc extension, hence the naming of "auto"-directives. To built a feature like this, I would suggest to go in the direction of https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html, this uses a Jinja templating pattern. We could mimick this a make a template for a classdef summary.

I would really appreciate a contribution here :)

MyClass
=====

MyClass docstring

Class Details
-------------
 %%class details%%
 
Constructor Summary
----------------------
%% List all contructors %%

Property Summary
-------------------
%% List all properties %%

Method Summary
-------------------
%% List all methods %%

[rdzman]

I'm not really familiar with the process Sphinx goes through when it produces HTML output, including the relationships between autodoc, autosummary, matlabdomain and core Sphinx functionality. But let me see if I roughly follow your idea. Correct me where I'm getting anything wrong.

Currently, using .. autoclass:: with :members: extracts docstrings from the source files, but it uses some hard-coded method to generate the output, whereas (for documenting Python code) autosummary uses templates to generate the output.

If that's the rough idea, here are a few questions:

• Aside from its additional functionality to generate stubs, etc., in terms of processing a single class, does autosummary still use autodoc to extract the same docstring info from the source files, and then just output it differently?
• Is the idea to modify autosummary to make it work with/recognize the matlabdomain? Or simply to borrow ideas from it to add new template-based functionality for classdefs directly to matlabdomain? Or something else? Maybe a matlabautosummary extension based on autosummary?
• Does autosummary work at all with Matlab code at the moment?

[joeced]

Hey - sorry not answering before.
At the current state, the autosummary feature of Python autodoc does not work with the MATLAB domain. In general I myself have not needed this feature, and just worked my way around it.
Most of the work I made, was ensuring that we could parse the MATLAB code without errors.
In another issue there might be a solution for what you need: #149 (comment)

[joeced]

Small update. It's way more difficult to add this feature than I thought. So no progress yet.

However, I did address this

The property names are shown with = None after them, which I don't want.

in version 0.16.0.

[rdzman]

Thanks @joeced.

I'm considering diving in to see if I can find a way to address some of the other issues I raised above. Is there any chance you'd be available to set up a brief call to help orient me? If so, feel free to e-mail me directly to arrange a time.

[rdzman]

First, thanks for #159, #171, #173, and #176 which together provide significant progress toward the goal of being able to write the help in my Matlab files in a way that works well for both Sphinx and MATLAB's help and doc commands.

Given this progress, I wanted to summarize the primary remaining issues I am facing and create separate issues (where needed) to track each. They are in rough priority order.

1. Autolinking of classes, functions, properties, methods in docstring text, or at the very least in the "See also" line. This one is first because I can't really write the missing documentation for my large MATLAB project until I know what to expect here and can make a decision on the conventions I'm going to use. More details and hopefully follow-up discussion/planning in auto-link functions, classes and members in docstring text #178.

2. Display of class members (e.g. Properties and Methods) in separate lists with corresponding headings. This does not affect how I write my documentation, but it is a high priority for me in terms of the quality of the final output from Sphinx. More details and hopefully follow-up discussion/planning in display class members in separate lists w/headings #179

3. Ability to use :inherited-members:. See implement :inherited-members: option for autoclass #180.

4. Autosummary features to build out stubs and summary tables. At the moment, I'm settling for writing my own script to generate the stub rST files. See also does Sphinx autosummary work with the MATLAB domain? #37 and matlabdomain does not recursively document folder/module? #149.

[joeced]

I'm happy to make this extension better. The long-term goal for me has also been to make the differences between MATLAB and Sphinx doc requirements as small as possible.

I need some time to sketch out the order of action items. First of is #171, which will make it easier to do the other steps. I hope you have a bit of patience as my effective time to work on the project is limited.

[rdzman]

I totally understand the limited time, so no pressure. And I very much appreciate your work on all of this.

The only thing that is time-critical for me is that I really need to get started on writing the documentation for my Matlab code. I need to make some assumption about the issues that affect how I write my source documentation.

So that would include #171, which I am going to assume will eventually be completed, and the auto-linking (item 1 above). For my current thoughts on the latter, see my follow up in #178.