Generate project documentation automatically

[JeremiePat]

As all good open source project, we need to have a good documentation. As much as possible we want that documentation to be generated automatically out of our code source and our various markdown files (markdown files is sort of a requirement as all Git manager such as GitHub or GitLab are able to render those file directly which made them very usable in that context)

To be able to do that we can assume that some tools such as JSDoc will be used, but JSDoc alone is almost useless. At minimum, we need to add a template to handle the look and feel of our documentation (very likely something customized) and possibly some extensions such as better-docs to make i a little bit smarter. So before picking a tool we need to answer some questions:

• How do we want to organize our documentation ?
• Which tools do we want to use ? (i.e. a doc generator or a static site generator)
• Which extension do we need to use with the chosen tools ?
• Do we want/need to create our own extension for our chosen tools ?

Feedback and opinions regarding those questions is highly welcome.