CDL-Based Sequence Documentation

[AntoineGautier]

This addresses #235.

The requirements and technical debts are described in this document: https://docs.google.com/document/d/1qObow0A18hq4nfmZY8vdcpYV-vOMIzkB5HJ4aLMmw-Q/edit?usp=sharing

To illustrate the new feature, the document at https://docs.google.com/document/d/12pnP6-vSE7AVGYGQPzi0PMyJVeeLhj2u/edit?usp=drive_link&ouid=100056680517301634140&rtpof=true&sd=true is created by

• running node ../modelica-json/app.js -f Buildings/Templates/Plants/Controls/HeatPumps/Validation/AirToWater.mo -o doc with commit bcc98069af of MBL (from private repo),
• opening the resulting HTML document with MS Word and from there:
  • including all images in the document with Edit > Links > (Ctrl+A to select all source files) Save picture in document,
  • inserting a table of contents,
  • saving as docx.

The same documentation with additional tables describing all parameters and I/O variables for each block is available at https://docs.google.com/document/d/100ZfL4T0VL5IzPjI2eqrEfuVhKuKlAxA/edit?usp=sharing&ouid=100056680517301634140&rtpof=true&sd=true
It is created by running
node ../modelica-json/app.js -f Buildings/Templates/Plants/Controls/HeatPumps/Validation/AirToWater.mo -o doc+ on the same commit of MBL, and using the same steps as above in MS Word.

[AntoineGautier]

@mwetter This is ready for review. (I've added the option to include tables of parameters, inputs and outputs in the documentation)

[mwetter]

This looks great.

A few comments:
In the generated Word document, there is a text

A staging matrix staEqu is required as a parameter. See the documentation of Buildings.Templates.Plants.Controls.StagingRotation.EquipmentEnable for the associated definition and requirements
Should this be a hyperlink to simulationresearch.lbl.gov/modelica/vXXX (based on the uses statement)?

When listing the parameters it would be good to reuse the tabs and groups from the Modelica annotation.

From a section, such as https://docs.google.com/document/d/1pceD7fS5jnLZ47zsf1FBODqVHPtaF3wD/edit#bookmark=id.2nusc19
how does one know what block (with the I/O and parameter listing in the Appendix) is used? Should there be a hyperlink so people can make the association?

The parameter listing does not show defaults, min and max. I assume this is intentional.

[AntoineGautier]

@mwetter Thanks for looking into this.

The block Buildings.Templates.Plants.Controls.StagingRotation.EquipmentEnable is not included in the documentation. This is as expected, because this block implements some internal signal conversion. For the blocks that are used in reference but not included in the documentation, the current implementation simply includes the name of the block without any hyperlink. I agree that fetching the library version with the uses annotation and creating a link to the online documentation for such blocks is what we should do. I simply did not implement it yet as I ran out of time for this development.

In dfb3a9b, I've added the tabs and groups to the parameter tables as you suggested.

At the end of each section, there is a new subsection added that provides the link to the block variables and the block name. In the example you give, there are subsections already included in the documentation of the block (with <h5> tags in the Documentation annotation), so the new subsection is actually this one: https://docs.google.com/document/d/1pceD7fS5jnLZ47zsf1FBODqVHPtaF3wD/edit#bookmark=id.40ew0vw
But with your example, I now wonder whether it would not be better to include the new subsection at the beginning rather than at the end. It may not be a numbered subsection but simply a paragraph. Please let me know what you think.

The parameter listing does not show defaults, min and max. This is as intended, because there is a unique table for each block definition, not for each block instance. Since defaults, min and max may be overridden at instanciation, providing these values would require one table for each instance.