search

almende / vis

⚠️ This project is not maintained anymore! Please go to https://github.com/visjs
7.85k stars 1.48k forks source link

Generate web page documentation from jsdoc #3383

Open macleodbroad-wf opened 7 years ago

macleodbroad-wf commented 7 years ago

Issue

Web page documentation lives separately from the code and is extra work to maintain. There have been a number of issues relating to out of date or incorrect documentation.

Proposed Solution

Port all interesting/descriptive content from the web page into the jsdocs and then generate the web pages from the jsdocs, as a gulp task.

Open Questions

Is there an existing template we can use? (ie one of the ones here: https://github.com/jsdoc3/jsdoc#templates)

Should we create a custom template that matches the existing visjs.org site?

Note

This issue can be assigned to me, but I'd like some feedback on the open questions before I begin, so that I do not waste effort pursuing this.

macleodbroad-wf commented 7 years ago

fyi @yotamberk - this may overlap with some of the work being done in https://github.com/almende/vis/issues/3364

yotamberk commented 7 years ago

Not necessarily

wimrijnders commented 7 years ago

Should we create a custom template that matches the existing visjs.org site?

I'd prefer this option.

I considered this some time ago, and my personal conclusion was to use something like EJS for the document generation. My overriding concern was to eliminate redundancy in the documentation, which is present a lot. However, this would not use the jsdoc tags.

A middle ground would be much better. I'm not convinced, though, that the documentation can be fully generated from just jsdoc tags.

yotamberk commented 7 years ago

I totally agree with @wimrijnders . We need to match the existing site. I'm too concern about how the docs will be generated and if they will really be beneficial to the user.

macleodbroad-wf commented 7 years ago

I agree that jsdoc alone is not enough to generate all of the documentation, however, there is a markdown plugin for jsdoc that allows you to generate pages from markdown + jsdoc.

I think we can port the existing site content to jsdoc with the markdown readme, and create a template which renders into the same state as the existing. We can also generate a strict subset, so that the docs generated are only those that are required to cover the user facing API.

The idea is just to remove/reduce the burden of updating documentation in two places (the jsdoc & the website), and rather just update the jsdoc, and have the website updated automatically.

wimrijnders commented 7 years ago

That sounds actually very good. Doing 'strict subsets' sounds like this could be implemented incrementally. And I totally agree with the motivation in the last paragraph.

Can you give a link to the plugin you mention?

macleodbroad-wf commented 7 years ago

Actually it looks like 3.3.0+ doesn't require the markdown plugin: http://usejsdoc.org/about-including-readme.html