Commit Graph

21 Commits

Author SHA1 Message Date
Justin Van Patten 7162491d0b
[docsgen] Fix rendering of deprecated messages and text in description lists ()
A change was made a while back to remove the use of shortcodes. As part
of that, the shortcode used to render markdown was replaced by a
function call that used goldmark to render markdown. The resulting HTML
from that wraps the text in paragraph tags.

This causes some problems for rendering the docs. For deprecations, the
deprecation message now shows up outside of the "Deprecated" box. This
happens because the rendered markdown was being wrapped in `<p></p>`
tags, leading to `<p class="resource-deprecated">Deprecated:
<p>message</p></p>`, which does not render correctly because paragraph
tags cannot be nested.

Also, in description lists, rendered markdown text was being wrapped in
paragraph tags (e.g. `<dd><p>text</p></dd>`), causing it to render
differently from text not wrapped in paragraph tags (e.g.
`<dd>text</dd>`).

This change addresses these issues.

- First, `<div class="resource-deprecated">` is used rather than `<p>`
to contain the deprecation information.

- Second, the `markdownify` function will now trim unnecessary paragraph
tags.

Fixes https://github.com/pulumi/pulumi-hugo/issues/2832
Fixes https://github.com/pulumi/registry/issues/3008

---

## Before

<img width="713" alt="Screen Shot 2023-08-24 at 5 21 44 PM"
src="https://github.com/pulumi/pulumi/assets/710598/1358cc74-dd8a-4bc0-bed8-603b1439b2aa">

## After

<img width="721" alt="Screen Shot 2023-08-24 at 5 21 58 PM"
src="https://github.com/pulumi/pulumi/assets/710598/ad501e68-1bac-486c-a723-7db2b3442c8a">

## Before

<img width="719" alt="Screen Shot 2023-08-24 at 5 22 28 PM"
src="https://github.com/pulumi/pulumi/assets/710598/6ca40b85-9008-429b-83c3-2f0d681752f3">

## After

<img width="714" alt="Screen Shot 2023-08-24 at 5 24 02 PM"
src="https://github.com/pulumi/pulumi/assets/710598/eec1dacf-8c24-470e-b1e3-da843b4aeaee">
2023-08-26 17:36:28 +00:00
aq17 b91126065b Update YAML invoke syntax for docs 2022-11-04 11:39:24 -07:00
Christian Nunciato 70e30c95b4
Fix the function template to show YAML under the YAML tab ()
* Fix function template to show YAML under the YAML tab
* Update template baselines
2022-05-06 16:19:25 -07:00
Christian Nunciato af8e010a4a Fix template layout issues, replace all shortcodes 2022-05-04 10:00:53 +02: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
Anton Tayanovskyy afcbcd3a51
7947: docgen for $fnOutput forms ()
* Toward doc gen of fn.Output version signatures

* Fixup Python docgen, and reorder forms so the direct form comes firs

* Respect go opt-out flag

* Fix tempalte bug with unbalanced HTML tags

* Edit CHANGELOG_PENDING.md

* Merge codeblocks in the function template

* Accept docs changes
2021-11-08 17:07:09 -05:00
Christian Nunciato e2b48d2f20
Fix up resource-docs links ()
Co-authored-by: Praneet Loke <1466314+praneetloke@users.noreply.github.com>
2021-02-09 09:04:02 -08:00
Paul Stack 5e8f219652
Reorder resource docs templates to make deprecated more prominent ()
Fixes: https://github.com/pulumi/docs/issues/4340

The deprecated message sits below the examples so it is not clear
to the user that the resource / datasource is deprecated
2020-10-07 21:25:25 +01:00
Justin Van Patten 988ebd8b8e
[codegen/docs] Don't emit API links in Azure NextGen resource docs ()
We're not going to generate language-specific API docs for the Azure NextGen provider, only resource docs. This change makes it so the resource docs do not emit any links to nonexistent API docs.
2020-09-20 11:56:52 -07:00
Justin Van Patten 92c0d1dc30
Docgen changes for Python input/output types ()
Resource doc changes for Python:

- Types are included in constructor/function args
- The property names for input/output types are now always snake_case, regardless of the generated mapping tables, to match the new input/output classes
- Some other minor tweaks to function/constructor signatures (e.g. removed the `__props__` arg, as it's not meant to be used directly; use `@staticmethod` for static `get` methods).
2020-08-19 08:34:06 -07:00
Praneet Loke 30b12cff49
[codegen/docs] Various Go-related fixes ()
* Remove code that was hiding Go as a language option for k8s overlay resources. Mark input args type for Functions as optional in Go.

* Show a special note in the Go function's snippet when the function name does not match other languages.

* Make sure the draft PR stays assigned to the original author. Add some more comments.

* Remove logic to use the Go ModuleToPackage map to then lookup the relevant C# namespace. Make getLanguageModuleName a method of modContext since passing in a package is not needed anymore.
2020-05-15 17:33:56 -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 fe3bd9ed99
[codegen/docs] Restore the API type links for C#. ()
* Restore the API type links for C#.

* Also restore them in function.tmpl.

* Add package details to the Functions template as well. Add a global template function to detect if the APIDocLinks has links for a language. Don't generate C# API doc links for k8s.
2020-05-01 17:13:56 -07:00
Praneet Loke 7b17463031
[codegen/docs] Fix the generation of Function names, args, and result type names ()
* Add a new DocLangHelper interface method to generate function names per language. Use the functionNames override map in Go to correctly generate a function name.

* Add kong to the title lookup map.

* Check if item was found in map.

* Use title case for the nodejs Function args type name. Use title case for the function name in the index page.

* Also fix the result name for a Function in nodejs to use title case.

* Use the module name to lookup the package.

* Use the title-case name for the Function name in the index page. Fix the language value passed to the lang chooser in function.tmpl.

* Use title case for nested type titles.

* Add title lookup for GitHub.
2020-04-27 17:47:01 -07:00
Sean Holung 5d9e3626b3
[codegen/docs] Improve titles tags and meta descriptions ()
* Optimize titles and descriptions

* Move regexp to file level variable

* wip

* Add title tags and description to module and pkg index pages

* Remove block_external_search_index from index.tmpl

* Improve resource descriptions

* Add more providers to look up map

* Improve module level descriptions

Clean up

cleanup

* Update the function.tmpl with the auto-generated disclaimer. Pass title tag and meta description for the function template as well.

* Fix whitespace in the package_details template..

* Account for empty module names for package-level resources. Move logic for generating title tag and description into separate methods for Resources and Functions.

* Add a test for the generated resource and function title tag.

Co-authored-by: Praneet Loke <1466314+praneetloke@users.noreply.github.com>
2020-04-21 12:28:44 +01:00
Justin Van Patten c04d1beaab
Fix header anchor ids in resource docs ()
* Add ids to headers so they can be linked to

* Make header ids more general

Rather than including the identifier in the name of the id, use a simpler more generic id.

* H3=>H2 for Modules/Resources/Functions/Package Details headings

This way, on individual resource/function pages, it doesn't make it look like "Package Details" is a sub heading under "Supporting Types" in the right-hand "ON THIS PAGE".
2020-04-18 02:45:47 -07:00
Christian Nunciato 7e46e7580f
Resource template fixes () 2020-03-31 04:07:04 -07:00
Christian Nunciato 21ee0919cd Update the resource-docs templates 2020-03-30 14:38:29 -07:00
Praneet Loke ab080c0c5d
Fix the signature for C# invokes in the resource docs generator ()
* Update the C# invoke signature in the Functions template used by resource docs generator.

* Add a new function to the DocLanguageHelper interface for resource docs generator to generate language-specific property names.

* Add a new DisplayName property to the propertyType struct for simpler display names without module names.

* Update templates to use the DisplayName property of propertyType. Strip the namespace/module name from type names for use as display names.
2020-03-23 14:17:14 -07:00
Praneet Loke 40f17faa73
Updates to resource doc generator for generating docs for Functions ()
* Added a new template for Functions. Implement the genFunction method for generating the docs for Functions.

* Rename type resourceArgs to resourceDocArgs. Minor updates the resource template.

* Generate nested types for Functions.

* Unexport types that don't need to be exported. Create the doc language helper objects in an init function and reuse them rather than recreating them every time. Update genNestedTypes to work with schema functions or resources.

* Fixed bug in nested type generation for Functions. Fixed bug in generating input and output doc links for nested types.
2020-03-11 17:58:12 -07:00