Add template for document generation with 'jsdoc'. (#3497)

* Add template for document generation with 'jsdoc'. In essence, it defines the subdirectory `docs` as a `jsdoc` template. Benefits: - allows the usage of partials, in order to DRY common parts of the html files. - makes available the jsdoc-comments, for addition into the documentation. - enables extraction of data from the source code. For example, the list of edge endpoints `['arrow', 'bar', 'circle']` can now be extracted from the source and inserted into the documentation on generation. In this initial version, the only file that has been changed is `docs/data/dataset.html`. In here, partials have been added to illustrate how common page elements can be DRY'd. The template has been set up in such a way, that resource files will be copied and that html files can pass through unchanged if no special template tags (`<?js...?>`) are used. This allows for a gradual transition of the html files to templates. **Usage:** `gulp docs` - The result files are placed in subdirectory `gen/docs/`. **NOTE:** The release procedure will have to be adjusted by adding this gulp command. The docs-files will then have to be taken from `gen/docs`. * Edits to docs/README * Adjusted layout of README.md * Further edits to README.md * Removed pre tags again in README.md - don't work in code block * Linted the gulpfile * Added proof of concept for docs generation from source
visjs · Jun 9, 2019 · 83ed1aa · 83ed1aa
1 parent c58b8cb
commit 83ed1aa
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,4 @@ npm-debug.log
 # temporary files
 .*.sw[op]
 .commits.tmp
+gen/
diff --git a/docs/network/index.html b/docs/network/index.html
@@ -1,3 +1,6 @@
+<?js
+  var self = this;
+?>
 <!DOCTYPE html>
 <html lang="en">
 <head>
@@ -609,6 +612,21 @@ <h2 id="methods">Methods</h2>
                     The options object is explained in full <a data-scroll="" data-options="{ &quot;easing&quot;: &quot;easeInCubic&quot; }" href="#optionsObject">below</a>.
                 </td>
             </tr>
+
+<?js
+  var comment = self.getComment("Network#findNode");
+?>
+            <tr class="collapsible toggle" onclick="toggleTable('methodTable','findNodeNew', this);">
+                <td colspan="2"><span parent="findNode" class="right-caret" id="method_findNodeNew"></span> 
+                    <?js= comment.prototype ?>  <b>This comes from the source!</b>
+            </tr>
+            <tr class="hidden" parent="findNodeNew">
+                <td class="midMethods">Returns: <?js= comment.returns ?></td>
+                <td>
+                   <?js= comment.description ?>
+                </td>
+            </tr>
+
             <tr class="collapsible toggle" onclick="toggleTable('methodTable','findNode', this);">
                 <td colspan="2"><span parent="findNode" class="right-caret" id="method_findNode"></span> findNode(
                     <code>String/Number nodeId</code>)

diff --git a/gulpfile.js b/gulpfile.js
@@ -10,6 +10,7 @@ var webpack = require('webpack');
 var uglify = require('uglify-js');
 var rimraf = require('rimraf');
 var argv = require('yargs').argv;
+var child_exec = require('child_process').exec;
 
 var ENTRY             = './index.js';
 var HEADER            = './lib/header.js';
@@ -29,7 +30,12 @@ var INDIVIDUAL_CSS_BUNDLES = [
   {entry: ['./lib/shared/**/*.css', './lib/network/**/*.css'], filename: 'vis-network.min.css'}
 ];
 
-// generate banner with today's date and correct version
+
+/**
+ * Generate banner with today's date and correct version
+ *
+ * @returns {string} banner text
+ */
 function createBanner() {
   var today = gutil.date(new Date(), 'yyyy-mm-dd'); // today, formatted as yyyy-mm-dd
   var version = require('./package.json').version;
@@ -39,6 +45,7 @@ function createBanner() {
       .replace('@@version', version);
 }
 
+
 var bannerPlugin = new webpack.BannerPlugin({
   banner: createBanner(),
   entryOnly: true,
@@ -92,6 +99,12 @@ var uglifyConfig = {
 // create a single instance of the compiler to allow caching
 var compiler = webpack(webpackConfig);
 
+/**
+ * Callback for handling errors for a compiler run
+ *
+ * @param {object} err
+ * @param {objects} stats
+ */
 function handleCompilerCallback (err, stats) {
   if (err) {
     gutil.log(err.toString());
@@ -232,5 +245,27 @@ gulp.task('lint', function () {
 });
 
 
+// Generate the documentation files
+gulp.task('docs', function(cb) {
+  var targetDir = 'gen/docs';
+
+  // Not sure if this is the best way to handle 'cb'; at least it works.
+  var hasError = false;
+  var onError = function(error) {
+    if (error !== undefined && error !== null) {
+      console.error('Error while running task: ' + error);
+      hasError = true;
+      cb();
+    }
+  }
+
+  rimraf(__dirname + '/' + targetDir, onError);  // Clean up previous generation
+
+  if (!hasError) {
+    var params = '-c ./jsdoc.json -r -t docs -d ' + targetDir;
+    child_exec('node ./node_modules/jsdoc/jsdoc.js ' + params + ' lib', undefined, cb);
+  }
+});
+
 // The default task (called when you run `gulp`)
 gulp.task('default', ['clean', 'bundle', 'minify']);
diff --git a/jsdoc.json b/jsdoc.json
@@ -0,0 +1,3 @@
+{
+  "plugins": ["plugins/markdown"]
+}
diff --git a/lib/network/Network.js b/lib/network/Network.js
@@ -470,7 +470,27 @@ Network.prototype.isActive = function () {
 Network.prototype.setSize             = function() {return this.canvas.setSize.apply(this.canvas,arguments);};
 Network.prototype.canvasToDOM         = function() {return this.canvas.canvasToDOM.apply(this.canvas,arguments);};
 Network.prototype.DOMtoCanvas         = function() {return this.canvas.DOMtoCanvas.apply(this.canvas,arguments);};
+
+
+/**
+ * Nodes can be in clusters. Clusters can also be in clusters. This function returns and array of
+ * nodeIds showing where the node is.
+ *
+ * If any nodeId in the chain, especially the first passed in as a parameter, is not present in
+ * the current nodes list, an empty array is returned.
+ *
+ * Example:
+ * cluster 'A' contains cluster 'B',
+ * cluster 'B' contains cluster 'C',
+ * cluster 'C' contains node 'fred'.
+ * `jsnetwork.clustering.findNode('fred')` will return `['A','B','C','fred']`.
+ *
+ * @param {string|number} nodeId
+ * @returns {Array}
+ */
 Network.prototype.findNode            = function() {return this.clustering.findNode.apply(this.clustering,arguments);};
+
+
 Network.prototype.isCluster           = function() {return this.clustering.isCluster.apply(this.clustering,arguments);};
 Network.prototype.openCluster         = function() {return this.clustering.openCluster.apply(this.clustering,arguments);};
 Network.prototype.cluster             = function() {return this.clustering.cluster.apply(this.clustering,arguments);};

diff --git a/package.json b/package.json
@@ -59,6 +59,7 @@
     "gulp-eslint": "^4.0.0",
     "gulp-rename": "^1.2.2",
     "gulp-util": "^3.0.8",
+    "jsdoc": "^3.5.5",
     "jsdom": "9.12.0",
     "jsdom-global": "^2.1.1",
     "merge-stream": "^1.0.1",