mirror of https://github.com/pulumi/pulumi.git
41 lines
3.1 KiB
Markdown
41 lines
3.1 KiB
Markdown
# Docs generator
|
|
|
|
This generator generates resource-level docs by utilizing the Pulumi schema.
|
|
|
|
## Crash course on templates
|
|
|
|
The templates use Go's built-in `html/template` package to process templates with data. The driver for this doc generator (e.g. tfbridge for TF-based providers) then persists each file from memory onto the disk as `.md` files.
|
|
|
|
Although we are using the `html/template` package, it has the same exact interface as the [`text/template`](https://golang.org/pkg/text/template) package, except for some HTML specific things. Therefore, all of the functions available in the `text/template` package are also available with the `html/template` package.
|
|
|
|
* Data can be injected using `{{.PropertyName}}`.
|
|
* Nested properties can be accessed using the dot notation, i.e. `{{.Property1.Property2}}`.
|
|
* Templates can inject other templates using the `{{template "template_name"}}` directive.
|
|
* For this to work, you will need to first define the named template using `{{define "template_name"}}`.
|
|
* You can pass data to nested templates by simply passing an argument after the template's name.
|
|
* To remove whitespace from injected values, use the `-` in the template tags.
|
|
* For example, `{{if .SomeBool}} some text {{- else}} some other text {{- end}}`. Note the use of `-` to eliminate whitespace from the enclosing text.
|
|
* Read more [here](https://golang.org/pkg/text/template/#hdr-Text_and_spaces).
|
|
* To render un-encoded content use the custom global function `htmlSafe`.
|
|
* **Note**: This should only be used if you know for sure you are not injecting any user-generated content, as it by-passes the HTML encoding.
|
|
* To print regular strings, that share the same syntax as the Go templating engine, use the built-in global function `print` [function](https://golang.org/pkg/text/template/#hdr-Functions).
|
|
* For example, if you need to render `{{% md %}}`, you will instead need to do `{{print "{{% md %}}"}}`.
|
|
|
|
Learn more from here: https://curtisvermeeren.github.io/2017/09/14/Golang-Templates-Cheatsheet
|
|
|
|
## `bundler.go`
|
|
|
|
This file contains a `main` function and is part of the `main` package. We run it using the `go generate` command (see the `Makefile` and the starting comment in `pkg/codegen/gen.go`).
|
|
|
|
> This file is ignored using a `+build ignore` comment at the top of the file, so it is not ignored during a `go build ...`.
|
|
|
|
## `packaged.go`
|
|
|
|
A file generated by `bundler.go` that contains formatted byte strings, that represent the string templates from the `./templates/` folder. This file is also git-ignored as it is intended to only be generated by the `docs` repo and is not used during runtime of the main Pulumi CLI. In fact, this whole package is not used during the runtime of the CLI itself.
|
|
|
|
## `go:generate`
|
|
|
|
> Read more [here](https://blog.golang.org/generate).
|
|
|
|
`go:generate` is a special code comment that can be used to run custom commands by simply running `go generate <package>`, which then scans for `go:generate` comments in all sources in the package `<package>`. It also serves as a way to document, that a certain file relies on a command to have been executed before it can be used.
|