SolarTherm
SolarTherm copied to clipboard
SolarTherm
Modelica HTML documentation
For users and potential developers of Modelica library, I think that we need to do the effort to integrate the documentation in each class/block/model with the annotation function. You know, the documentation must be where they expect to be. Otherwise, people miss part of our work. I'm sure to this task is tedious, but the result looks very nice.
Are tools like doxygen/sphinx available for Modelica, so that we can publish our class/block/model documentation online?
I went looking for this a while back and found something within OpenModelica. There is a MetaModelica file that they use to generate the standard library documentation. I hijacked that and edited it so that it would generate the doc from OpenModelica to html. I didn't automate it and include it in the source code because I'm not sure about licencing and the like. Once we have the html I'm not sure where we are going to host it. Maybe it is possible on read the docs or github pages.
There might be another tool out there I missed?
The documentation online is useful only in the case of people are working with the whole tool. But what happen with the people who are only interested in the Modelica code? Independent of the simulation scripts, the models are implemented in Modelica. How can people understand the code if they need to look website when they want to know what do some specific model? The best way to document Modelica code is in html with annotation function. You can take a look of how other Modelica libraries are documented, an always is the same.
There are two types of coders in the worlds... those who use IDEs/GUIs, and those who don't. Whatever approach we use must provide usable documentation to both these groups.
I suggest that the right approach is to use annotations for the reference information relating to our Modelica code, but to keep the information there fairly succinct and put longer-form stuff eg examples/tutorials in the readthedocs stuff. In parallel, we need a way of publishing the reference information to a website, such that the non-IDE/GUI users can read it in a convenient form.
OM can extract the documentation annotation: https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/scripting_api.html#getdocumentationannotation
