Create PoC for generating API docs

[vansimke]

Create a proof of concept that automatically generates the API documentation for Dojo 2's repos from the source code. Ideally, solution shouldn't be too rigid - consider the creation of an intermediate format (e.g. JSON) that is then transformed into the final HTML.

[vansimke]

I'm planning on starting by creating an importer that works for a single file for example @dojo/core/Evented.ts. Goal will be to have it parse the API (external aspects of the module) and store it in a TS data structure. From there, if things look favorable, we can move on to export a neutral format (such as JSON), or use the existing code to perform the additional transformations that are required to generate the HTML. In the later case, the in-memory TS data structure would serve as the neutral format.

Estimated time: 3 days

[devpaul]

I've forked from @vansimke's development branch and added functionality for using the docviewer (from theintern.io) with the new designs. Created a docs branch here so we can continue work.

[devpaul]

Remaining work to implement the new designs:

• Table of Contents

1. Highlight the current article/page
2. Expand the current selection w/ sub-nav

• Docs Viewer

1. Fill the Table of Contents sub-nav for the current page/document w/ sub-page items

• Cleanup styles

1. Desktop (cleanup)
2. Tablet (implement)
3. Mobile (implement hamburger)

• Dojo READMEs

1. Update all of the Dojo 2 project readmes to include docviewer content w/ links to api.json and other pages for sub-nav

• Dojo 2 APIs

1. Build Dojo 2 APIs
2. Add building docs as part of the build step in dojo/grunt-dojo2 so it builds api.json when the project builds
3. Update the api.json build to use TS 2.6 (current 2.4)

[devpaul]

WIP branch here: https://github.com/dojo/dojo.io/tree/docs

I've updated the docviewer to so it highlights the selected topic in the table of contents.

Remaining

• Create and fill a sub-nav that expands under the active topic/page
• Cleanup desktop styles and implement mobile/tablet menu

[jason0x43]

I have another WIP branch at https://github.com/jason0x43/dojo.io/tree/itorrey-docs-revamp. It's based off if Torrey's design work in (not surprisingly) the itorrey-docs-revamp branch in his fork. The doc viewer code is a bit different because I started from a different direction, but the API code is mostly the same.

[jason0x43]

I pushed a number of updates to the viewer code, mostly to clean up the rendering flow and fix some IE11 issues. The latest version points to forks of repos that contain API docs (cli, core, has, widget-core, widgets) and the canonical repos for everything else.

[devpaul]

Closing this. We currently generate API docs via an api.json file via Intern's tooling.