Commit Graph

7 Commits

Author SHA1 Message Date
Florian Stadler 74e8928cff
Add ability to constrain supported languages of resource and function overlays ()
The existing overlays (e.g. Chart v3 in Kubernetes, or CallbackFunction
in AWS) are not available in every language Pulumi supports. This often
confuses users because the generated docs include all languages Pulumi
supports (e.g. see
https://github.com/pulumi/pulumi-kubernetes/issues/2181).

To solve that problem, this change adds a new optional parameter to the
schema that allows configuring the languages an overlay (resource or
function) supports.
To support this in docsgen the existing Language Chooser
(`LangChooserLanguages`) of resources is made configurable and extended
to functions.

Note: This doesn't support resource methods right now. They'll need
extra handling because and overlay resource method might not support all
of the languages its resource supports. I'll tackle this in a follow up
PR.

Here's a screenshot of how this will look like for the Helm v3 chart for
example:
<img width="1046" alt="Screenshot 2024-07-01 at 16 11 23"
src="https://github.com/pulumi/pulumi/assets/2453580/b1a1365a-6dee-4099-829a-2859639a4c8c">

The PR contains the following commits. I'd recommend to look at the
first three ones and then check the regenerated golden files in the last
one:
- **Add schema parameter to constrain supported languages for overlays**
- **Update developer docs and changelog**
- **Refactor LanguageChooser and always pass supported languages**
- **Regenerate testdata**

relates to 
2024-07-09 14:54:50 +00:00
Mikhail Shilkov 2583e0291d Extend API doc generation 2022-05-04 10:00:53 +02:00
Christian Nunciato 0a0f48e292
Replace Hugo shortcodes () 2022-04-29 15:04:15 -07:00
Christian Nunciato c20bdbe945
Update resource-docs templates to adjust for Hugo upgrade () 2021-03-14 07:24:55 -07:00
Praneet Loke aa313aecf8
[codegen/docs] Add a new template for examples section ()
* Add a new template for examples section. Extract the examples section into a structured format for custom template processing.

* Update the description IFF we were able to extract examples sections from it.

* Update doc comments and add missing file header for the newly added file.

* Make the example description readable. Add a check for empty example sections.

* Add a chooser right below the Example Usage header. Remove javascript as a language.

* Allow an empty new-line between short-codes boundaries.
2020-05-08 16:25:28 -07:00
Praneet Loke 9abc65d3c6
Remove hard-coded Bucket examples from the schema-based docs generator. ()
* Also remove the Examples property from the resourceDocArgs type since the resource Comment will contain the multi-lang examples on their surrounded by a shortcode.
2020-03-12 13:16:08 -07:00
Praneet Loke edbb05dddd
Update schema-based docs generator ()
* Update properties.tmpl to render property comment as-is. WIP splitting out properties to lang-specific tables.

* Generate the constructor dynamically from the resource per language.

* Add doc functions in each language generator package for getting doc links for types..and later other functions too.

* Render the constructor params in the Go code and inject into the template.

* Generate nodejs types using the nodejs lang generator.

* Add a templates bundler. Added a new Make target for autogenerating a static bundle for the resource docs generator.

* Generate type links for all languages based on their schema type. Render the property type with a link if the underlying elements have a supporting type. Fix word-breaks for Python type names.

* Various changes including the introduction of an interface type under the codegen package to help with generating some language-specific information for the resource docs generator.

* Add a function to explicitly generate links for input types of nested types. Fix the resource doc link generator for Go. Don't replace the module name from the nodejs language type.

* Fix bug with C# property type html encoding.

* Fix some template formatting. Pass the state inputs for Python to generate the lookup function for it.
* Do not generate the examples section if there are none.

* Generating the property types per language.

* Formatting. Rename function for readability.

* Add comments. Update README.

* Use relative URLs for doc links within the main site
2020-03-09 10:35:20 -07:00