Splitting vis.js docs into multiple modules

[mojoaxel]

This is an sub-issue of #2405

How to handle documentation in an separate project?

[mojoaxel]

I see the following possibilities:

Central

Keep the docs in one major repository (e.g almende/vis)

Pros

• We can keep the current doc-folder as it is.
• The doc-generation mechanism must only be maintained once.

Cons

• API-Changes must be done in multiple repositories (source and docs). -> Thats a bad one!!

Decentral

Every module has his own documentation.

Pros

• Docs and code are not separated and can be changed together in the same PR.
• The docs only include the parts that are interesting to the user.

Cons

• There is no central docs folder to show e.g. on the website.
• It could be hard to keep the look.and-feel of all docs consistent.

[wimrijnders]

A bit of both. There are two levels of documentation:

1. The documentation per module. This should be part of a module
2. The encompassing documentation for the website. This should be handled separately.

• The per-module docs should be able to stand alone per module
• We make scripts to integrate the first with the second.
• Common elements can be defined as a template which can be require'd.

I draw your attention to #3497, which makes a template out of the documentation. This can be carried further to split out the common parts of the template, which can be handled separately. This is in fact one of the main reasons for the PR, the other being that documentation can now be generated from the source.