Automatically generate docs from component definitions

[langestefan]

I've been going through the code / docs quite a bit these past few days, because I'm adding some components I need.

Is your feature request related to a problem? Please describe.

Some components have no documentation (HeatingResistor for example), some components have incomplete documentation. Fields like states and connectors are manually typed and there is no standardization in how those parts of the docs are formatted. This makes it more difficult to find what you need.

Describe the solution you’d like

Instead of manually putting docstrings at the top of component definitions I suggest we directly generate documentation from the fields inside @mtkmodel. In particular description, bounds, guess, unit and any other fields that are available from the metadata: Symbolic Metadata. This avoids the need to type everything twice. We can still have a docstring at the top with a broader description. The fields can be automatically generated and put in a table for example.

This is an example of what I would like to achieve: https://developers.home-assistant.io/docs/core/entity/number

[ChrisRackauckas]

Yes, definitely agreed this would be a nice thing to add. That's a more of an MTK issue to improve the macro though.

[langestefan]

Let me know if you have any ideas and where I can contribute.

[ChrisRackauckas]

You can programmatically generate docstrings like how it's done for Num:

https://github.com/JuliaSymbolics/Symbolics.jl/pull/649/files#diff-b8c0c7fd71b608d8ede7feac325fbfa572e06bd50bc32f0b835f3dbe61bb7fa5R174-R185

We can do this on the object that's generated by the macro to have it construct the docstring using the information in the object itself.

[hersle]

I think this could also be a great way to offload some information from show(). The display of sys could prioritize the numerical aspect which is convenient for interactive use (e.g. equations, number of equations, variables, default values, ...), while ?sys could prioritize the verbose/linguistic representation (name, description, ...).

In addition to variable descriptions, the new AbstractSystem description could also be natural to use.

[ChrisRackauckas]

Yes that's a very good point.

[langestefan]

I think we should follow the implementation of DocStringExtensions.jl

And then add new abbreviation(s)?

[ChrisRackauckas]

That would work.