Create an API doc generator for JavaScript and Python

[lindydonna]

For launch, the current TypeDoc solution is good enough, especially since generated .ts and d.ts files will be available. However, it is very inflexible, so we should explore how to make better generated reference content.

Ideally, we'd split out Python and JavaScript into their own pages, using a layout that is familiar to users of each language.

[lindydonna]

Putting in M16 as a placeholder.

[joeduffy]

Pulling this in to see if there's any way to expedite. Not having this is tough, especially since a considerable chunk of figuring out Pulumi is trying to figure out the names of types and properties of the resources you care about. IDE support helps, but is not perfect, and it's even more painful because our names diverge from CloudFormation, ARM, etc., due to Terraform's naming.

[lindydonna]

Beta user feedback:

If I'm looking at the pulumi/aws API ref docs, there is no way to navigate to pulumi/cloud, or vice versa

[joeduffy]

We made some good progress on this in 70637ee.

The following major steps are remaining:

• Check in the new API docs for all packages
• Fix Kubernetes doc-gen bug (nested modules related)
• Retire the old ones
• Fix variables to display detailed values
• Add member anchors for deep linking
• Experiment with expanding types w/ properties (a la Godoc)
• Scrub short package names to be legal identifiers
• Print literal types (rather than { ... })
• Perform intra-package linking
• Perform inter-package linking (where possible)
• Fix code overflow styling (to match what GitHub does)
• Consider restyling the file list somehow (e.g., add a "Module Files" header)
• Make Index, et. al collapsable
• Check in generated code so our GitHub linking works
• Add fancy logos to spruce up the clouds packages page

[lindydonna]

@joeduffy Please make sure your fix for code overflow styling will also also apply to inline blocks such as this one:

[joeduffy]

There seems to be a bug that prevents some code from highlighting correctly. See https://docs.pulumi.com/reference/pkg/nodejs/@pulumi/kubernetes/core/v1/#Pod as an example (scroll halfway down the page).

[joeduffy]

@swgillespie this is the work item I just mentioned. Putting it into 0.15.1, but if you see any things in the above checklist that are easy wins, and don't have any other urgent issues, let's whittle away at this.

[lukehoban]

I've moved the pending work to #492, and I'll close this one out.