WID-14 Improve the HTML representation on a Traited obj in Jupyter lab

[rarescodemart]

I converted the description for each model from RST format to HTML and I managed to render the mathematical equations (which are present in it) using MathJax.

[liadomide]

The result would look as in the attached image

[i-Zaak]

The result would look as in the attached image

This looks great! However is there a reason to duplicate the class docstrings in the dfun?

[liadomide]

This looks great! However is there a reason to duplicate the class docstrings in the dfun?

dfun.__doc__ is expected to have only the equations (plus minimum text in some cases). The Class docstring is more generic and the eq there help for the overall description of the Model.

It is a decision we made a long time ago, to keep the eq in both places.
Some places which have less space to display (here, the PhasePlane in tvb web GUI) are better if only the equations are given. The overall Sphinx generated documentation can benefit for the class extended documentation.

It might be that we need to revise this decision...
For the current task we only took the existent convention/state and worked on the display in jupyterlab ;-)

[i-Zaak]

I see, wasn't aware of that - in that case it of course makes sense. I guess the class docstring then would be shown for the component instance representation, to render e.g. the Coupling equations.

Alternatively one could keep the simulator representation as is (no equations) and show more details for the individual components separately.

[i-Zaak]

And one more thing - do you want to do some more improvements for the HTML representations in this PR, or just focus on the equations?

[liadomide]

And one more thing - do you want to do some more improvements for the HTML representations in this PR, or just focus on the equations?

Very good question. Could we delay answering until our next call 17 Jan? Then we can have a small demo with the current state, and we decide how to proceed...
Then, we would not merge until after 17th

[i-Zaak]

Could we delay answering until our next call 17 Jan?

Of course. In the meantime, these might be relevant in the long-term:

• Need for modern formatting of docstrings in inline help(something) and in separate something? window ipython/ipython#3687
• Use in JupyterLab currently?  python-lsp/docstring-to-markdown#25
• https://github.com/jupyter/papyri

[liadomide]

Alternatively one could keep the simulator representation as is (no equations) and show more details for the individual components separately.

That might be a more generic strategy to follow (instead of the current code in this PR).
Because on Model we have dfun._doc__ (as used here), but Coupling has only an equation on the class doc (in this PR not shown)

[liadomide]

This has a nice outcome on the Class HTML representation, but I am not convinced the ipython dependency is healthy, being here at the very core (where the MetaClass for HasTraits is defined).

@maedoc @i-Zaak what do you think ?
Is it useful to keep also this Class HTML representation for jupyter, or users will be ok with only the instance representations (see comments bellow with exemples)

[liadomide]

With only one dependency in tvb.basic.neotraits.info towards docutils, we get the following on instance level:

For a model instance :

A coupling instance:

And the simulator:

@i-Zaak would this outcome be ok ?