pulumi / registry

The global index of everything you can do with Pulumi.
https://www.pulumi.com/registry
Apache License 2.0
24 stars 110 forks source link

[Epic] Decouple provider API docs generation from pulumi/pulumi #3834

Open cnunciato opened 5 months ago

cnunciato commented 5 months ago

The tight coupling of resourcedocsgen to the pulumi/pulumi repository (where page templating currently resides) makes debugging and fixing page rendering issues exceedingly complex. To give the docs team the agility it needs to be able to maintain the end-to-end docs experience, we'd like to remove the process of templating API docs from pulumi/pulumi and bring it into pulumi/registry where it cab be managed on its own.

### Tasks
- [ ] https://github.com/pulumi/registry/issues/3896
- [ ] https://github.com/pulumi/registry/issues/3918
- [ ] Adapt resourcedocsgen or registrygen to consume this JSON
- [ ] Copy the templates into the Registry repo
- [ ] Build the docs with these templates and JSON
- [ ] Remove the templates, etc., from pulumi/pulumi
- [ ] https://github.com/pulumi/registry/issues/3966
sean1588 commented 5 months ago

Just some thoughts here -- after doing a bit more investigation, I'm not sure if I am convinced that moving the templates to the registry is a good idea. I think it sounds good in theory, but there is definitely dependencies between the templates and the codegen code as it relies on the structs defined there in order to render. There are also dependecies between the templates and the tests that run in that repository. If we move the templates here, anyone making changes to codegen would need to rely on templating here in order to test and that process is already a complex enough and adding more complexity to working with that, I'm not sure out weighs the benefits we would gain by moving it.