The Road to JSDocs

[leobauza]

We are moving documentation to JSDoc3. This means the site will be generated through JSDoc annotations and markdown docs will also be generated through JSDoc annotations from the same source. Since JSDoc allows us to make tutorials we will add those as well.

• Set up JSDoc task and configuration (should generate a site)
• Set up task to run JSDoc generated site for development
• Set up transition folders while we catch up JSDoc annotations to existing markdown docs (new_docs for markdown and new_site for generated html site)
• Move all existing API documentation to JSDoc annotations
• Add testing + recipes tutorials (copy from existing site)
• Theme docs to look like our current site
• Add a custom front page (copy from existing site)
• Once JSDocs are caught up to current documentation overwrite docs with new_docs and site with new_site
• Generate markdown docs from JSDoc output (postponed until after JSDoc site is ready)
• Figure out versioning of docs. (probably a task to write to subfolders of docs and site
• Figure out how to publish versioned docs (ie. don't overwrite version folders when pushing gh-pages branch)
• Add examples as tutorials (examples may be in a different repo by this time)
  • Update instructions to run any of the examples.
  • Explain why these examples exist (what feature are they highlighting?)
  • Include possible problems running the examples (eg. if port :3000 is in use an error is thrown)
  • Update both the /examples README.md and each example's README.md

[leobauza]

• Find out if there is a way to use Flow annotations to generate the docs (eliminating the need for JSDoc annotations when Flow annotations exist)