This repository has been archived by the owner on Jul 29, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
1 parent
0a6f257
commit 24d61cb
Showing
11 changed files
with
523 additions
and
82 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -16,3 +16,4 @@ npm-debug.log | |
| # temporary files | ||
| .*.sw[op] | ||
| .commits.tmp | ||
| gen/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,231 @@ | ||
| # 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: | ||
|
|
||
| ```js | ||
| { | ||
| "_":["../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: | ||
|
|
||
| ```js | ||
| { | ||
| "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: | ||
|
|
||
| ```js | ||
| { | ||
| "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: | ||
|
|
||
| ```js | ||
| 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 ' * /'* | ||
|
|
||
| ```js | ||
| { | ||
| "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: | ||
|
|
||
| ```js | ||
| var tmp = data().filter({name:'_drawText'}).get(); | ||
| ``` | ||
|
|
||
| Full output returned: | ||
|
|
||
| ```js | ||
| [{ | ||
| "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: | ||
|
|
||
| ```js | ||
| 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: | ||
|
|
||
| ```js | ||
| var docData = { | ||
| myTitle: 'Hello, pussycat!' | ||
| }; | ||
| ``` | ||
|
|
||
| Within the template: | ||
|
|
||
| ``` | ||
| <?js= myTitle ?> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.