Finalize resource-oriented API doc generation

[justinvp]

Finalize resource-oriented doc gen, with any follow-ups that came out of #2263 (e.g. missing data in schema, refinements to the style/design of page, etc.).

---

The final page anatomy is as follows:

• Generate real docs pages for Data Sources (prototype was focused on Resources only)
• Declarations in each language
  • Call into individual language generators to generate these declarations in each language
• Emit nested types inline
• Linking of types within declarations
  • Make the declaration gen smarter to include links
  • Linking within the page (e.g. anchor links to nested structures)
  • Linking within the site (e.g. linking types like pulumi.Input to their associated SDK doc link https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/pulumi/#Input)
• Show how to read an existing resource (i.e. static get function)

A few remaining layout-specific questions remain:

• Import an existing resource on the bottom of the page
  • We will not do this for Q1. Based on the final docs experience, we will see how this can be best documented.
  • In Pulumi, a resource can be imported by passing the custom resource option import with the appropriate resource ID as its value.
• How do we handle rendering of Comment for each language? (see Add place to hold examples in schema pulumi-terraform-bridge#122)
  • i.e. if the “comment” for a resource’s property contains symbols, how do we “fix-up” the symbol to have the correct casing for the specified language?
• Do we need any special handling of aliases?
  • Aliases will be added to the docs after Q1.
• How do we handle language-specific overlays? (e.g. NodeJS-specific functions like onObjectCreated on Bucket):
  • With the "old way", we show these in the docs, since they are members on the resource class.
  • For Q1, we decided this is not essential. However, certain types of overlays are necessary for language-specific things such as enums, which we plan on including in the resource-level docs. For that see Add enum support to the schema and code generators pulumi#4003.

[praneetloke]

Closing this issue as the outstanding questions have been resolved. I will open separate work items for the applicable ones.