Merge pull request #249 from AntoineGautier/issue235_cdlDoc

CDL-Based Sequence Documentation

.gitignore

@@ -15,3 +15,4 @@ modelica-json.log
 /cxf
 .nyc_output
 .DS_Store
+.vscode

.travis.yml

@@ -2,7 +2,7 @@ dist: focal
 
 language: node_js
 node_js:
-  - "18"
+  - "20"
 
 env:
   - MODELICAPATH="./.tmp/"

README.md

@@ -26,11 +26,11 @@ First, set the MODELICAPATH environment variable by adding the following line to
 export MODELICAPATH=${MODELICAPATH}:/usr/local/Modelica/Library/
 ```
 
-The parser requires Java and node. The java dependency can be installed using: 
+The parser requires Java and node. The java dependency can be installed using:
 ```
 sudo apt-get install default-jdk default-jre
 ```
-The node version should be >= 18 and you can use [Node Version Manager](https://nodejs.org/en/download/package-manager) to set it up. Following is using 0.39.7 version: 
+The node version should be >= 18 and you can use [Node Version Manager](https://nodejs.org/en/download/package-manager) to set it up. Following is using 0.39.7 version:
 ```
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 source ~/.bashrc
@@ -60,7 +60,7 @@ make clean-installation
 
 ### Windows
 
-- First, make sure that both the `modelica-json` directory and the `Modelica Buildings Library` directory are in the folders that do not require administrator access. 
+- First, make sure that both the `modelica-json` directory and the `Modelica Buildings Library` directory are in the folders that do not require administrator access.
   By saving the directories in driver other than `C:\` would typical avoid the administrator access issue.
 
 - Then, create the `MODELICAPATH` environment variable and set the value as the path of Modelica Buildings Library, like `E:\modelica-buildings` or `E:\modelica-buildings-master`.
@@ -99,7 +99,9 @@ This parser takes a .mo file in input and has three possible outputs, that can b
 - **raw-json** : detailed transcription of a Modelica file in JSON
 - **json**: simplified JSON format, easier to read an interpret
 - **semantic**: generate semantic model from semantic information included within `annotation` in the Modelica file
-- **cxf**: generate CXF representation in `.jsonld` of a CDL sequence complying with ASHRAE S231P 
+- **cxf**: generate CXF representation in `.jsonld` of a CDL sequence complying with ASHRAE S231P
+- **doc**: create the documentation of the sequence of operation in an HTML document
+- **doc+**: create the documentation of the sequence of operation and the list of all variables in an HTML document
 
 ##### --mode / -m
 
@@ -122,12 +124,12 @@ If `-p` flag is specified, the JSON output conforms to prettyprint. The default
 
 ##### --elementary
 
-If `--elementary` flag is specified, the CXF (jsonld) files for the elementary blocks are also generated. Else, they are ignored. The default option is `false`. 
+If `--elementary` flag is specified, the CXF (jsonld) files for the elementary blocks are also generated. Else, they are ignored. The default option is `false`.
 `-o`/`--output` should be `cxf`.
 
 ##### --cxfCore
 
-If `--cxfCore` flag is specified, generate the  CXF-core.jsonld files for all the elementary blocks. The default option is `false`.  
+If `--cxfCore` flag is specified, generate the  CXF-core.jsonld files for all the elementary blocks. The default option is `false`.
 `-o`/`--output` should be `cxf`, `-f`/`--file` should be `path/to/CDL` and `--elementary` flag must be used.
 
 ## 4. JSON Schemas
@@ -148,7 +150,7 @@ Graphical viewers are available (please use right click + open in a new tab or r
 
 [CXF-Core.jsonld](CXF-Core.jsonld) contains the CXF representation of all CDL elementary blocks, classes and relationships.
 
-To generate the `CXF-Core.jsonld`, use: 
+To generate the `CXF-Core.jsonld`, use:
 
 ```
 node app.js -f <path/to/modelica-buildings>/Buildings/Controls/OBC/CDL -o cxf --elementary --cxfCore

app.js

@@ -3,6 +3,7 @@ const pa = require('./lib/parser.js')
 const ut = require('./lib/util.js')
 const se = require('./lib/semanticExtractor.js')
 const ce = require('./lib/cxfExtractor.js')
+const dc = require('./lib/cdlDoc.js')
 
 const logger = require('winston')
 const path = require('path')
@@ -19,7 +20,7 @@ parser.addArgument(
   ['-o', '--output'],
   {
     help: 'Specify output format.',
-    choices: ['raw-json', 'json', 'modelica', 'semantic', 'cxf'],
+    choices: ['raw-json', 'json', 'modelica', 'semantic', 'cxf', 'doc', 'doc+'],
     defaultValue: 'json'
   }
 )
@@ -119,11 +120,12 @@ if (args.output === 'modelica') {
       throw new Error('In order to generate CXF-core.jsonld containing all elementary blocks, --elementary flag must be used.')
     }
   }
+  let jsons // Array of json representations of all mo files recursively instantiated by the top-level class
   const completedJsonGeneration = new Promise(
     function (resolve, reject) {
       const moFiles = ut.getMoFiles(args.file)
       // Parse the json representation for moFiles
-      pa.getJsons(moFiles, args.mode, args.output, args.directory, args.prettyPrint, args.elementary, args.cxfCore)
+      jsons = pa.getJsons(moFiles, args.mode, args.output, args.directory, args.prettyPrint, args.elementary, args.cxfCore)
       resolve(0)
     }
   )
@@ -134,6 +136,12 @@ if (args.output === 'modelica') {
     if (args.output === 'cxf' && args.cxfCore && args.elementary) {
       ce.getCxfCore(args.file, args.directory, args.prettyPrint)
     }
+    if (args.output === 'doc' || args.output === 'doc+') {
+      const unitData = JSON.parse(
+        fs.readFileSync(path.join(__dirname, 'units-si.json'), 'utf8'))
+      const includeVariables = (args.output === 'doc+')
+      dc.buildDoc(jsons[0], jsons, unitData, args.directory, includeVariables)
+    }
   })
 }