Add template for document generation with 'jsdoc'. #3497

wimrijnders · 2017-09-29T04:28:34Z

In essence, this PR 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. 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.

A README.md has been added to subdirectory docs, with notes on how to use the jsdoc-generated comment data.

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.

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`.

mbroad

This looks promising. Quite well documented.
I will have to pull it down and give it a try!

mbroad · 2017-09-30T00:11:45Z

docs/README.md

+
+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.


This should be on the same line, and people can use word wrap in their ide to have the line break appropriately.

ok. It should be readable as text as well, of course.

mbroad · 2017-09-30T12:12:39Z

docs/README.md

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


You can get proper syntax highlighting by adding the name to your code block.

ie,

```javascript var docData =... ```

json is also a valid key word for syntax highlighting

yeah, I knew that, it just didn't occur to me to use it here.

var msg = 'js works as well.';

And now I learnt from you how to display ```js itself!

Please do keep on reviewing! And yes try it out, please, if only to see if it works on machines other than mine.

macleodbroad-wf · 2017-10-01T01:12:13Z

gulpfile.js

+      hasError = true;
+      cb();
+    }
+  }


missing semi-colon

macleodbroad-wf · 2017-10-01T01:12:23Z

gulpfile.js

+  if (!hasError) {
+    var params = '-c ./jsdoc.json -r -t docs -d ' + targetDir;
+    child_exec('node ./node_modules/jsdoc/jsdoc.js ' + params + ' lib', undefined, cb);
+  };


unnecessary semi-colon

Due to this, I linted gulpfile.js and to my delight, I discovered that it's actually possible. What do you think, should it officially be added to the linting step?

macleodbroad-wf · 2017-10-01T01:29:46Z

I found that the index.html files did not work as I would have expected them to? Maybe this is a misunderstanding on my part.

wimrijnders · 2017-10-01T05:05:23Z

The top index.html has this redirect in it which possibly reconnects to the main site. But all the other, lower-level, index.html's should be just fine.

The top-level index.html can be excused; do you have trouble with the other ones as well?

mbroad · 2017-10-01T15:47:45Z

Maybe I'm misunderstanding how to use this.

If I navigate to dataset.html directly, everything looks fine.

If I open the index.html file, I'm redirected, but file not found.

If I copy and paste the entire file structure into the docs the gh-pages branch, replacing existing files, then the index pages work, but show file listings.

It is entirely possible that this is just user error.

In any case the generated dataset.html looks great.

wimrijnders · 2017-10-01T16:08:43Z

You're not misunderstanding anything; that's how the html files are set up. These pages are made to be integrated into the web site, as in gh-pages. So, locally the redirect goes nowhere. Another thing I notice is that the links in the menu's are hardcoded, i.e. they take you to somewhere on http://visjs.org.

show file listings

Perhaps you mean that they don't show?

As for the greatness of the generated page, it should be just identical to the original version. Next step is to isolate all the common parts in partials - obvious candidates: the HTML at top and bottom, the menu's. And there are plenty more duplicates of data in the doc's themselves, e.g. font settings in both nodes and edges.

Hoping for some help in converting them....

mbroad · 2017-10-01T16:30:07Z

And will that also mean eventually incorporating documentation on the web page that is generated from some of the jsdoc in the source code itself?

wimrijnders · 2017-10-01T17:45:42Z

Oh yes, definitely. That is in fact the major point of this exercise. The rest is just nice consequences.
In fact, one of the major todo's of this documentation thing is proving that this is feasible.

mbroad · 2017-10-01T18:40:16Z

Excellent!

wimrijnders · 2017-10-02T05:16:23Z

Since the whole point of using jsdoc for document generation is to be able to use the header comments, I've added a proof of concept. Diffing should make everything clear.

* 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

wimrijnders added the Docs label Sep 29, 2017

Edits to docs/README

5061dc4

mbroad suggested changes Sep 30, 2017

View reviewed changes

wimrijnders added 3 commits September 30, 2017 19:40

Adjusted layout of README.md

c732bdf

Further edits to README.md

6ba6a5b

Removed pre tags again in README.md - don't work in code block

4fc9c7f

macleodbroad-wf reviewed Oct 1, 2017

View reviewed changes

Linted the gulpfile

b6f71f4

mbroad approved these changes Oct 1, 2017

View reviewed changes

Added proof of concept for docs generation from source

39c1ba0

macleodbroad-wf approved these changes Oct 15, 2017

View reviewed changes

This was referenced Oct 17, 2017

Splitting vis.js docs into multiple modules #3579

Open

Splitting vis.js sources into multiple modules #2405

Open

yotamberk merged commit 24d61cb into almende:develop Oct 20, 2017

wimrijnders deleted the docTemplate branch October 21, 2017 04:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add template for document generation with 'jsdoc'. #3497

Add template for document generation with 'jsdoc'. #3497

wimrijnders commented Sep 29, 2017

mbroad left a comment

mbroad Sep 30, 2017

wimrijnders Sep 30, 2017

mbroad Sep 30, 2017

mbroad Sep 30, 2017

wimrijnders Sep 30, 2017

wimrijnders Sep 30, 2017

macleodbroad-wf Oct 1, 2017

wimrijnders Oct 1, 2017

macleodbroad-wf Oct 1, 2017

wimrijnders Oct 1, 2017

macleodbroad-wf commented Oct 1, 2017

wimrijnders commented Oct 1, 2017

mbroad commented Oct 1, 2017

wimrijnders commented Oct 1, 2017

mbroad commented Oct 1, 2017

wimrijnders commented Oct 1, 2017 •

edited

Loading

mbroad commented Oct 1, 2017

wimrijnders commented Oct 2, 2017

Add template for document generation with 'jsdoc'. #3497

Add template for document generation with 'jsdoc'. #3497

Conversation

wimrijnders commented Sep 29, 2017

mbroad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

macleodbroad-wf commented Oct 1, 2017

wimrijnders commented Oct 1, 2017

mbroad commented Oct 1, 2017

wimrijnders commented Oct 1, 2017

mbroad commented Oct 1, 2017

wimrijnders commented Oct 1, 2017 • edited Loading

mbroad commented Oct 1, 2017

wimrijnders commented Oct 2, 2017

wimrijnders commented Oct 1, 2017 •

edited

Loading