search

cdklabs / construct-hub

AWS CDK construct library that can be used to deploy instances of the Construct Hub in any AWS Account.
https://constructs.dev
Apache License 2.0
202 stars 26 forks source link

Guidance: JSII fixtures and documentation generation #771

Closed dontirun closed 3 days ago

dontirun commented 2 years ago

Construct Hub auto compiles the examples in READMEs to other languages. Due to JSII limitations for non-compiled examples there can be errors (like this one https://github.com/cdklabs/cdk-nag/issues/583).

Is it possible to use JSII fixtures to influence the resultant translations on Construct Hub? If so, is there a way to test the translation before attempting to publish a new version?

kaizencc commented 2 years ago

Hi @dontirun, taking a stab at this one. I am familiar with how this works on the CDK, less so with Construct Hub, but hopefully its similar.

The tool that does the translations is called jsii-rosetta. In particular, the extract command is what translates the examples and determines if they compile or not. The readme linked should have decent documentation on how to get it working for your use case to test.

Here's my workflow when I'm working on the CDK repo: after I make changes to the CDK readme examples, I build to get a .jsii file and then call yarn --silent jsii-rosetta extract --compile, which extracts the examples it finds in the .jsii file into a .jsii.tabl.json "tablet" file. The tablet holds information on whether an example successfully compiled or not, and any errors should be displayed in stdout as well.

Now about rosetta fixtures, here is better documentation for that than what you linked. You can use them as scaffolding to avoid repeating yourself in the visible example. I'd recommend taking a look at some of the modules in the CDK repo. For any module (example, you'll find a rosetta folder that holds a default.ts-fixture, which is the scaffolding for most examples in that repo. If you build the module with ../../../scripts/buildup, you can then see what I'm talking about when you run yarn rosetta:extract, which will create the .jsii.tabl.json file in the module's folder.

Hope this helps! Let me know if you have more questions.

dontirun commented 2 years ago

Fixtures may not be what I'm looking for. I'm expecting a majority of the users to read the example from the repository README versus documentation that is generated for the documentation site. The default README isn't going to display the examples with the fixtures added.

Thanks for the documentation link and insight @kaizen3031593, this is really helpful! I'll take some time to dive into it and see what I can figure out.