Docs : fixes and enhancements for the documentation template. (#3596)

* Docs : fixes and enhancements for the documentation template.

This is an evolutionary update for the `jsdoc` document generation.

- Added functionality to retrieval of data comments
- Added partial for generating documentation in the method tables.
- Moved commenting to source for `Network#clusterOutliers`. This was used as a case example.

- Adjustment to CSS to get the decription text margins same as original
- Added step to generate documentation to release checklist
- Fixed some commenting which `jsdoc` couldn't handle

* Fixes for linting

docs/css/style.css

@@ -191,6 +191,15 @@ td.indent2 {
     padding-left:50px !important;
 }
 
+td p:first-child {
+    margin-top: 0;
+}
+
+td p:last-child {
+    margin-bottom: 0;
+}
+
+
 pre.options {
     max-width:600px;
 }

docs/network/index.html

@@ -552,51 +552,10 @@ var locales = {
                     The options object is described for <code>clusterByConnection</code> and does the same here.
                 </td>
             </tr>
-            <tr class="collapsible toggle" onclick="toggleTable('methodTable','clusterOutliers', this);">
-                <td colspan="2"><span parent="clusterOutliers" class="right-caret" id="method_clusterOutliers"></span> clusterOutliers(
-                    <code>[Object options]</code>)
-            </tr>
-            <tr class="hidden" parent="clusterOutliers">
-                <td class="midMethods">Returns: none</td>
-                <td>This method will cluster all nodes with 1 edge with their respective connected node.
-                    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>)
-            </tr>
-            <tr class="hidden" parent="findNode">
-                <td class="midMethods">Returns: Array</td>
-                <td>Nodes can be in clusters. Clusters can also be in clusters. This function returns and array of
-                    nodeIds showing where the node is.
+<?js= self.partial('tmpl/renderMethod.tmpl', "Network#clusterOutliers") ?>
+<?js= self.partial('tmpl/renderMethod.tmpl', "Network#findNode") ?>
 
-                    <br><br>
-                    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.
-
-                    <br><br> Example:
-                    cluster 'A' contains cluster 'B',
-                    cluster 'B' contains cluster 'C',
-                    cluster 'C' contains node 'fred'.
-                    <code>network.clustering.findNode('fred')</code> will return <code>['A','B','C','fred']</code>.
-                </td>
-            </tr>
             <tr class="collapsible toggle" onclick="toggleTable('methodTable','getClusteredEdges', this);">
                 <td colspan="2"><span parent="getClusteredEdges" class="right-caret" id="method_getClusteredEdges"></span> getClusteredEdges(
                     <code>String baseEdgeId</code>)

docs/publish.js

@@ -54,15 +54,37 @@ function createRenderer(fromDir, data) {
    */
   renderer.getComment = function(methodName) {
     var tmp = data().filter({longname: methodName}).get()[0];
-	  //console.log(JSON.stringify(tmp));
+
+    if (tmp === undefined) {
+      throw new Error('Could not find jsdoc for: ' + methodName);
+    }
+
+    // NOTE: Following does not show up with `gulp docs`, need to do call directly
+	  // console.log(JSON.stringify(tmp, null, 2));
 
     // Some restructuring, to adapt it to the docs layout
     // This needs some work to make it handle 0 and > 1 parameters
-    var param = tmp.params[0];
-    var prototype = tmp.name + '(<code>' + param.type.names.join('|') + ' ' + param.name  + '</code>)';
-    var returns = tmp.returns[0].type.names;
+    var paramText = "";
+    if (tmp.params !== undefined && tmp.params.length > 0) {
+      let param = tmp.params[0];
+      let tmpText = param.type.names.join('|') + ' ' + param.name;
+      if (param.optional === true) {
+        tmpText = '[' + tmpText + ']';
+      }
+      paramText = '<code>' + tmpText + '</code>';
+    }
+    var prototype = tmp.name + '(' + paramText + ')';
+
+    var returns = 'none';
+    if (tmp.returns !== undefined && tmp.returns.length > 0) {
+      let name = tmp.returns[0].type.names[0];
+      if (name !== "undefined") {
+        returns = name;
+      }
+    }
 
     return {
+      name: tmp.name,
       prototype: prototype,
       returns: returns,
       description: tmp.description

docs/tmpl/renderMethod.tmpl

@@ -0,0 +1,18 @@
+<?js
+  //
+  // Output the HTML for showing a method description in a method table.
+  //
+  var methodName = obj;
+  var self = this;
+  var comment = self.getComment(methodName);
+?>
+            <tr class="collapsible toggle" onclick="toggleTable('methodTable','<?js= comment.name ?>', this);">
+                <td colspan="2"><span parent="<?js= comment.name ?>" class="right-caret" id="method_<?js= comment.name ?>"></span> 
+                    <?js= comment.prototype ?>
+            </tr>
+            <tr class="hidden" parent="<?js= comment.name ?>">
+                <td class="midMethods">Returns: <?js= comment.returns ?></td>
+                <td>
+                   <?js= comment.description ?>
+                </td>
+            </tr>

lib/network/Network.js

@@ -497,7 +497,16 @@ Network.prototype.cluster             = function() {return this.clustering.clust
 Network.prototype.getNodesInCluster   = function() {return this.clustering.getNodesInCluster.apply(this.clustering,arguments);};
 Network.prototype.clusterByConnection = function() {return this.clustering.clusterByConnection.apply(this.clustering,arguments);};
 Network.prototype.clusterByHubsize    = function() {return this.clustering.clusterByHubsize.apply(this.clustering,arguments);};
+
+/**
+ * This method will cluster all nodes with 1 edge with their respective connected node.
+ * The options object is explained in full <a data-scroll="" data-options="{ &quot;easing&quot;: &quot;easeInCubic&quot; }" href="#optionsObject">below</a>.
+ *
+ * @param {object} [options]
+ * @returns {undefined}
+ */
 Network.prototype.clusterOutliers     = function() {return this.clustering.clusterOutliers.apply(this.clustering,arguments);};
+
 Network.prototype.getSeed             = function() {return this.layoutEngine.getSeed.apply(this.layoutEngine,arguments);};
 Network.prototype.enableEditMode      = function() {return this.manipulation.enableEditMode.apply(this.manipulation,arguments);};
 Network.prototype.disableEditMode     = function() {return this.manipulation.disableEditMode.apply(this.manipulation,arguments);};

lib/network/modules/components/shared/LabelSplitter.js

@@ -243,8 +243,12 @@ class MarkupAccumulator {
   /**
    * Create a regular expression for the tag if it isn't already one.
    *
+   * The return value is an array `[RegExp, number]`, with exactly two value, where:
+   *  - RegExp is the regular expression to use
+   *  - number is the lenth of the input string to match
+   *
    * @param {string|RegExp} tag  string to match in text
-   * @returns {[RegExp, number]}  regular expression to use and length of input string to match
+   * @returns {Array}  regular expression to use and length of input string to match
    * @private
    */
   prepareRegExp(tag) {

misc/RELEASE_CHECKLIST_TEMPLATE.md

@@ -66,7 +66,8 @@ If we would merge the development branch would overwrite this. To solve this we
 ## Update website
 - [ ] update the gh-pages branch: `git checkout gh-pages && git pull && git checkout -b "gh-pages_vX.Y.Z"`
 - [ ] Copy the `dist` folder from the `master` branch to the `github-pages` branch in another directory, overwriting existing files: `cp -rf ../vis_vX.Y.Z/vis/dist .`
-- [ ] Copy the `docs` folder from the `master` branch to the `github-pages` branch in another directory, overwriting existing files: `cp -rf ../vis_vX.Y.Z/vis/docs .`
+- [ ] Generate the documentation: `gulp docs`
+- [ ] Copy the `gen/docs` folder from the `master` branch to the `github-pages` branch in another directory, overwriting existing files: `cp -rf ../vis_vX.Y.Z/vis/gen/docs .`
 - [ ] Copy the `examples` folder from the `master` branch to the `github-pages` branch in another directory, overwriting existing files: `cp -rf ../vis_vX.Y.Z/vis/examples .`
 - [ ] Check if there are new or updated examples, and update the gallery screenshots accordingly.
 - [ ] Update the library version number in the `index.html` page.
@@ -83,4 +84,4 @@ If we would merge the development branch would overwrite this. To solve this we
 - [ ] FORCE-Push the branches to github: `git push --force && git push --tag`
 - [ ] [Re-Enable branch protection](https://github.com/almende/vis/settings/branches/develop) (enable ALL checkboxes) for `develop`.
 
-DONE!
+DONE!