API docs issues

[lukehoban]

There is no helm module at https://pulumi.io/reference/pkg/nodejs/@pulumi/kubernetes/index.html, seems we show v2 there (which should be a submodule of helm)?

There are no/few docs on https://pulumi.io/reference/pkg/nodejs/@pulumi/kubernetes/v2/, apparently because we use // comments instead of /** **/ JS doc comments.

[lblackstone]

@lukehoban I'm not sure how the API docs are generated, but point 2 seems to be due to a lack of doc comments on a very large generated list:

pulumi-kubernetes/sdk/nodejs/provider.ts

Lines 107 to 115 in bb8a2d6

	/**
	* getResource returns a resource defined by a built-in Kubernetes group/version/kind and name.
	*
	* For example:
	* getResource("apps/v1/Deployment", "nginx")
	*/
	public getResource(groupVersionKind: "admissionregistration.k8s.io/v1alpha1/InitializerConfiguration", name: string): pulumi.Output<admissionregistration.v1alpha1.InitializerConfiguration>;
	public getResource(groupVersionKind: "admissionregistration.k8s.io/v1alpha1/InitializerConfiguration", namespace: string, name: string): pulumi.Output<admissionregistration.v1alpha1.InitializerConfiguration>;
	public getResource(groupVersionKind: "admissionregistration.k8s.io/v1alpha1/InitializerConfigurationList", name: string): pulumi.Output<admissionregistration.v1alpha1.InitializerConfigurationList>;

I'm not sure if it would make sense to generate a huge number of nearly identical comments, or if there is some way to suppress most of them and only document the high-level usage.

I'm still looking into the other issues.

[lukehoban]

I think the problem is actually all the uses of //. Those docs aren’t picket up by the doc generator.

Re: the overloads - I’m not sure whether that prevents generating useful IDE and/ doc content - but if it does I’d argue we should generate as many comments as needed.

[lblackstone]

Helm is showing up as v2 in the API docs because the resources live in the v2 namespace, which is then imported under the helm namespace in the kubernetes-provider:

pulumi-kubernetes/sdk/nodejs/index.ts

Lines 2 to 3 in 08eb3b9

	import * as helm from "./helm";
	export { helm };

I think the preferred solution would be to move Helm resources to a separate package (#175), but we could possibly also update tsdocgen to handle this special case.

[lblackstone]

I've poked at this for a bit, and decided I need to work on some basic cleanup before I can address the doc issues. The root cause of the k8s API doc problems seem to be related to the tsdocgen tool, and the fact that the k8s provider is laid out very differently than the terraform-generated providers.

I'm going to tackle #479 as a starting point, and try to make the layout match what tsdocgen is expecting.

Given the extra scope of the work, this won't make it in for M21, but should land early in M22.