vis.js is a dynamic, browser-based visualization library
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Francesco Stefanini 991331d35b [Timeline] Vertical group labels (#3795) 6 years ago
..
css Docs : fixes and enhancements for the documentation template. (#3596) 7 years ago
data Fixed typo (#3742) 7 years ago
fonts Fix broken links to docs assets 9 years ago
graph2d [Timeline] Year quarters (#3717) 7 years ago
graph3d Moved navbar elements in all html documentation files to partial (#3604) 7 years ago
img yay! new search for visjs.org 9 years ago
js polising the network docs a little 9 years ago
network Add `icon` option to ShapeBase (#3756) 7 years ago
timeline [Timeline] Vertical group labels (#3795) 6 years ago
tmpl Docs : fixes and enhancements for the documentation template. (#3596) 7 years ago
README.md Add template for document generation with 'jsdoc'. (#3497) 7 years ago
index.html added breadcrumbs to all pages 9 years ago
publish.js Docs : fixes and enhancements for the documentation template. (#3596) 7 years ago

README.md

Command line usage example

jsdoc -c jsdoc.json -r -t docs -d gen/docs lib
  • -c: use this config file for jsdoc
  • -r: Recurse into subdirectories of the specified source directories
  • -t: Use template in path docs
  • -d: Generated html files put in gen/docs
  • Source files to parse are taken from directory lib

Notes

The template generation is set up so that:

  • Files ending in .tmpl are skipped
  • All non-html files are plain copied
  • html-files can contain <?js ?> tags, but this is not required

Intention

The docs directory is treated as a jsdoc template, in which the html-files are the template files. This allows for a gradual adaptation of the html-files to templates; unchanged html-files will pass through jsdoc unchanged.

The added value of using jsdoc for documentation generation, is that the complete documentation information, as collected by jsdoc from the source, is available for usage. This way, it's possible to insert technical notes from the source code into the documentation.


Usage of and Notes on Source Code

This section contains notes on the usage of jsdoc functionality, to aid with the handling of its generated data.

Parameters of publish()

Parameter taffyData

A table containing all data collected from the source code, related to jsdoc generation. See below for more info and example outputs.

Parameter opt

Example of opt variable:

{
  "_":["../github/vis/lib/network/"],
  "configure":"jsdoc.json",
  "recurse":true,
  "template":"/home/wim/projects/jsdoc/default",
  "destination":"./out/",
  "encoding":"utf8"
}

Parameter tutorial

This does not appear to be of use for the generation of vis.js documentation.

Example of tutorial variable:

{
  "longname":"",
  "name":"",
  "title":"",
  "content":"",
  "parent":null,
  "children":[],
  "_tutorials":{}
}

Global variable env

This contains addition info for the current execution of jsdoc. Example of env variable:

{
  "run":{"start":"2017-09-16T05:06:45.621Z","finish":null},
  "args":["-c","jsdoc.json","-r","-t","default","../github/vis/lib/network/"],
  "conf":{
    "plugins":["/usr/lib/node_modules/jsdoc/plugins/markdown.js"],
    "recurseDepth":10,
    "source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":""},
    "sourceType":"module",
    "tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},
    "templates":{"monospaceLinks":false,"cleverLinks":false}
  },
  "dirname":"/usr/lib/node_modules/jsdoc",
  "pwd":"/home/wim/projects/jsdoc",
  "opts":{ <<same as parameter 'opt' above>> },
  "sourceFiles":[ <<list of full path names of all js-source files used as input>> ],
  "version":{"number":"3.5.4","revision":"Fri, 04 Aug 2017 22:05:27 GMT"}
}

taffyData

This is a parameter to publish(). It's a table containing all data collected from the source code, related to jsdoc generation.

I can't find any way to return a list of fields for the data items in the taffyDB docs, therefore below there are examples of items, for better understanding of usage.

Example usage:

  var data = taffyData;
  var tmp = data().filter({name:'Label'}).get();

Returns an array with all items with name === 'Label'. Example output of one of these items, for a class:

In these examples, block comment endings are redacted to ' * /'

{
  "comment":"/**\n * A Label to be used for Nodes or Edges.\n * /",
  "meta":{
    "range":[3770,41303],
    "filename":"Label.js",
    "lineno":167,
    "columnno":0,
    "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
    "code":{
      "id":"astnode100065034",
      "name":"Label",
      "type":"ClassDeclaration",
      "paramnames":["body","options","edgelabel"]
    }
  },
  "classdesc":"
A Label to be used for Nodes or Edges.

",
  "name":"Label",
  "longname":"Label",
  "kind":"class",
  "scope":"global",
  "params":[
    {"type":{"names":["Object"]},"name":"body"},
    {"type":{"names":["Object"]},"name":"options"},
    {"type":{"names":["boolean"]},"optional":true,"defaultvalue":false,"name":"edgelabel"}
  ],
  "___id":"T000002R005289",
  "___s":true
}

Example of item for an instance method:

  var tmp = data().filter({name:'_drawText'}).get();

Full output returned:

[{
  "comment":"/**\n *\n * @param {CanvasRenderingContext2D} ctx\n * @param {boolean} selected\n * @param {boolean} hover\n * @param {number} x\n * @param {number} y\n * @param {string} [baseline='middle']\n * @private\n * /",
  "meta":{
    "range":[20060,22269],
    "filename":"Label.js",
    "lineno":652,
    "columnno":2,
    "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
    "code":{
      "id":"astnode100066427",
      "name":"Label#_drawText",
      "type":"MethodDefinition",
      "paramnames":["ctx","selected","hover","x","y","baseline"]
    },
    "vars":{"":null}
  },
  "params":[
    {"type":{"names":["CanvasRenderingContext2D"]},"name":"ctx"},
    {"type":{"names":["boolean"]},"name":"selected"},
    {"type":{"names":["boolean"]},"name":"hover"},
    {"type":{"names":["number"]},"name":"x"},
    {"type":{"names":["number"]},"name":"y"},
    {"type":{"names":["string"]},"optional":true,"defaultvalue":"'middle'","name":"baseline"}
  ],
  "access":"private",
  "name":"_drawText",
  "longname":"Label#_drawText",
  "kind":"function",
  "memberof":"Label",
  "scope":"instance",
  "___id":"T000002R005388",
  "___s":true
}]

jsdoc template rendering

See function createRenderer(fromDir, data) in code for usage.

There are two calls for rendering templates:

  • var html = renderer.render(inFile, docData);
  • var html = renderer.partial(inFile, docData);

The difference is that render() will use a default layout template, if present, which will encapsulate all html. This can be set by:

  renderer.layout = 'path/to/default/layout.tmpl'; 

Parameter docData is a hash which is used to pass parameters into a template. The standard way of using this appear to be:

<?js
  var data = obj;   // Whatever docData is
  var self = this;
?>

But it also appear to be possible to use the elements of docData directly:

var docData = {
  myTitle: 'Hello, pussycat!'
};

Within the template:

  <?js= myTitle ?>