From bd668c5a60a29944b3de4364f27f93c04e5ff8b7 Mon Sep 17 00:00:00 2001 From: wimrijnders Date: Sat, 28 Oct 2017 23:42:06 +0200 Subject: [PATCH] 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 | 9 ++++ docs/network/index.html | 45 +------------------ docs/publish.js | 30 +++++++++++-- docs/tmpl/renderMethod.tmpl | 18 ++++++++ lib/network/Network.js | 9 ++++ .../components/shared/LabelSplitter.js | 6 ++- misc/RELEASE_CHECKLIST_TEMPLATE.md | 5 ++- 7 files changed, 72 insertions(+), 50 deletions(-) create mode 100644 docs/tmpl/renderMethod.tmpl diff --git a/docs/css/style.css b/docs/css/style.css index 3a1d060e..1e9d4cc8 100644 --- a/docs/css/style.css +++ b/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; } diff --git a/docs/network/index.html b/docs/network/index.html index f60ca719..b641d69b 100644 --- a/docs/network/index.html +++ b/docs/network/index.html @@ -552,51 +552,10 @@ var locales = { The options object is described for clusterByConnection and does the same here. - - clusterOutliers( - [Object options]) - - - Returns: none - This method will cluster all nodes with 1 edge with their respective connected node. - The options object is explained in full below. - - - - - - - This comes from the source! - - - Returns: - - - - - - findNode( - String/Number nodeId) - - - Returns: Array - 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'. - network.clustering.findNode('fred') will return ['A','B','C','fred']. - - getClusteredEdges( String baseEdgeId) diff --git a/docs/publish.js b/docs/publish.js index f500e366..938da486 100644 --- a/docs/publish.js +++ b/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 + '(' + param.type.names.join('|') + ' ' + param.name + ')'; - 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 = '' + tmpText + ''; + } + 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 diff --git a/docs/tmpl/renderMethod.tmpl b/docs/tmpl/renderMethod.tmpl new file mode 100644 index 00000000..b218e7c1 --- /dev/null +++ b/docs/tmpl/renderMethod.tmpl @@ -0,0 +1,18 @@ + + + + + + + Returns: + + + + \ No newline at end of file diff --git a/lib/network/Network.js b/lib/network/Network.js index b45baf0a..f0f3a240 100644 --- a/lib/network/Network.js +++ b/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 below. + * + * @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);}; diff --git a/lib/network/modules/components/shared/LabelSplitter.js b/lib/network/modules/components/shared/LabelSplitter.js index 75ad77b6..5ef0fc6d 100644 --- a/lib/network/modules/components/shared/LabelSplitter.js +++ b/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) { diff --git a/misc/RELEASE_CHECKLIST_TEMPLATE.md b/misc/RELEASE_CHECKLIST_TEMPLATE.md index 8369c1b6..b2c92e02 100644 --- a/misc/RELEASE_CHECKLIST_TEMPLATE.md +++ b/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! \ No newline at end of file +DONE!