Browse Source

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
mbroad/code-climate-coverage-develop
wimrijnders 7 years ago
committed by Yotam Berkowitz
parent
commit
bd668c5a60
7 changed files with 72 additions and 50 deletions
  1. +9
    -0
      docs/css/style.css
  2. +2
    -43
      docs/network/index.html
  3. +26
    -4
      docs/publish.js
  4. +18
    -0
      docs/tmpl/renderMethod.tmpl
  5. +9
    -0
      lib/network/Network.js
  6. +5
    -1
      lib/network/modules/components/shared/LabelSplitter.js
  7. +3
    -2
      misc/RELEASE_CHECKLIST_TEMPLATE.md

+ 9
- 0
docs/css/style.css View File

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

+ 2
- 43
docs/network/index.html View File

@ -552,51 +552,10 @@ var locales = {
The options object is described for <code>clusterByConnection</code> and does the same here. The options object is described for <code>clusterByConnection</code> and does the same here.
</td> </td>
</tr> </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);"> <tr class="collapsible toggle" onclick="toggleTable('methodTable','getClusteredEdges', this);">
<td colspan="2"><span parent="getClusteredEdges" class="right-caret" id="method_getClusteredEdges"></span> getClusteredEdges( <td colspan="2"><span parent="getClusteredEdges" class="right-caret" id="method_getClusteredEdges"></span> getClusteredEdges(
<code>String baseEdgeId</code>) <code>String baseEdgeId</code>)

+ 26
- 4
docs/publish.js View File

@ -54,15 +54,37 @@ function createRenderer(fromDir, data) {
*/ */
renderer.getComment = function(methodName) { renderer.getComment = function(methodName) {
var tmp = data().filter({longname: methodName}).get()[0]; 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 // Some restructuring, to adapt it to the docs layout
// This needs some work to make it handle 0 and > 1 parameters // 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 { return {
name: tmp.name,
prototype: prototype, prototype: prototype,
returns: returns, returns: returns,
description: tmp.description description: tmp.description

+ 18
- 0
docs/tmpl/renderMethod.tmpl View File

@ -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>

+ 9
- 0
lib/network/Network.js View File

@ -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.getNodesInCluster = function() {return this.clustering.getNodesInCluster.apply(this.clustering,arguments);};
Network.prototype.clusterByConnection = function() {return this.clustering.clusterByConnection.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);}; 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.clusterOutliers = function() {return this.clustering.clusterOutliers.apply(this.clustering,arguments);};
Network.prototype.getSeed = function() {return this.layoutEngine.getSeed.apply(this.layoutEngine,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.enableEditMode = function() {return this.manipulation.enableEditMode.apply(this.manipulation,arguments);};
Network.prototype.disableEditMode = function() {return this.manipulation.disableEditMode.apply(this.manipulation,arguments);}; Network.prototype.disableEditMode = function() {return this.manipulation.disableEditMode.apply(this.manipulation,arguments);};

+ 5
- 1
lib/network/modules/components/shared/LabelSplitter.js View File

@ -243,8 +243,12 @@ class MarkupAccumulator {
/** /**
* Create a regular expression for the tag if it isn't already one. * 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 * @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 * @private
*/ */
prepareRegExp(tag) { prepareRegExp(tag) {

+ 3
- 2
misc/RELEASE_CHECKLIST_TEMPLATE.md View File

@ -66,7 +66,8 @@ If we would merge the development branch would overwrite this. To solve this we
## Update website ## Update website
- [ ] update the gh-pages branch: `git checkout gh-pages && git pull && git checkout -b "gh-pages_vX.Y.Z"` - [ ] 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 `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 .` - [ ] 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. - [ ] Check if there are new or updated examples, and update the gallery screenshots accordingly.
- [ ] Update the library version number in the `index.html` page. - [ ] 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` - [ ] 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`. - [ ] [Re-Enable branch protection](https://github.com/almende/vis/settings/branches/develop) (enable ALL checkboxes) for `develop`.
DONE!
DONE!

Loading…
Cancel
Save